Skip to contentSkip to conversation

rust: sync: introduce `LockClassKey`

PATCH Superseded Wedson Almeida Filho 8 participants 34 messages Apr 5, 2023 – Apr 8, 2023

Subsystems (3)

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/13 rust: sync: introduce `LockClassKey`

From: Wedson Almeida Filho <[email protected]>

It is a wrapper around C's lock_class_key, which is used by the synchronisation primitives that are checked with lockdep. This is in preparation for introducing Rust abstractions for these primitives.

---
v1 -> v2: Fixed a typo in comment

 rust/kernel/sync.rs | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
rust/kernel/sync.rs +45 -0
index 33da23e3076d..84a4b560828c 100644
@@ -5,6 +5,51 @@
 //! This module contains the kernel APIs related to synchronisation that have been ported or
 //! wrapped for usage by Rust code in the kernel.
 
+use crate::types::Opaque;
+
 mod arc;
 
 pub use arc::{Arc, ArcBorrow, UniqueArc};
+
+/// Represents a lockdep class. It's a wrapper around C's `lock_class_key`.
+#[repr(transparent)]
+pub struct LockClassKey(Opaque<bindings::lock_class_key>);
+
+// SAFETY: `bindings::lock_class_key` is designed to be used concurrently from multiple threads and
+// provides its own synchronization.
+unsafe impl Sync for LockClassKey {}
+
+impl LockClassKey {
+    /// Creates a new lock class key.
+    pub const fn new() -> Self {
+        Self(Opaque::uninit())
+    }
+
+    #[allow(dead_code)]
+    pub(crate) fn as_ptr(&self) -> *mut bindings::lock_class_key {
+        self.0.get()
+    }
+}
+
+/// Defines a new static lock class and returns a pointer to it.
+#[doc(hidden)]
+#[macro_export]
+macro_rules! static_lock_class {
+    () => {{
+        static CLASS: $crate::sync::LockClassKey = $crate::sync::LockClassKey::new();
+        &CLASS
+    }};
+}
+
+/// Returns the given string, if one is provided, otherwise generates one based on the source code
+/// location.
+#[doc(hidden)]
+#[macro_export]
+macro_rules! optional_name {
+    () => {
+        $crate::c_str!(core::concat!(core::file!(), ":", core::line!()))
+    };
+    ($name:literal) => {
+        $crate::c_str!($name)
+    };
+}
Signature · 1 line
2.34.1
#1 lore raw

PATCH v2 2/13 rust: sync: introduce `Lock` and `Guard`

From: Wedson Almeida Filho <[email protected]>

They are generic Rust implementations of a lock and a lock guard that contain code that is common to all locks. Different backends will be introduced in subsequent commits.

---
v1 -> v2: No changes

 rust/kernel/sync.rs      |   2 +-
 rust/kernel/sync/lock.rs | 160 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 161 insertions(+), 1 deletion(-)
 create mode 100644 rust/kernel/sync/lock.rs
rust/kernel/sync.rs +1 -1
index 84a4b560828c..bf088b324af4 100644
@@ -8,6 +8,7 @@
 use crate::types::Opaque;
 
 mod arc;
+pub mod lock;
 
 pub use arc::{Arc, ArcBorrow, UniqueArc};
 
@@ -25,7 +26,6 @@ impl LockClassKey {
         Self(Opaque::uninit())
     }
 
-    #[allow(dead_code)]
     pub(crate) fn as_ptr(&self) -> *mut bindings::lock_class_key {
         self.0.get()
     }
rust/kernel/sync/lock.rs new file +160 -0

160 lines not on this page · raw message

Signature · 1 line
2.34.1
#2 lore raw

PATCH v2 3/13 rust: lock: introduce `Mutex`

In reply to Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This is the struct mutex lock backend and allows Rust code to use the kernel mutex idiomatically.

Cc Peter Zijlstra <[email protected]>
Cc Ingo Molnar <[email protected]>
Cc Will Deacon <[email protected]>
Cc Waiman Long <[email protected]>

---
v1 -> v2: No changes

 rust/helpers.c                 |   7 ++
 rust/kernel/sync.rs            |   1 +
 rust/kernel/sync/lock.rs       |   2 +
 rust/kernel/sync/lock/mutex.rs | 118 +++++++++++++++++++++++++++++++++
 4 files changed, 128 insertions(+)
 create mode 100644 rust/kernel/sync/lock/mutex.rs
rust/helpers.c +7 -0
index 09a4d93f9d62..3010a2ec26e2 100644
@@ -21,6 +21,7 @@
 #include <linux/bug.h>
 #include <linux/build_bug.h>
 #include <linux/refcount.h>
+#include <linux/mutex.h>
 
 __noreturn void rust_helper_BUG(void)
 {
@@ -28,6 +29,12 @@ __noreturn void rust_helper_BUG(void)
 }
 EXPORT_SYMBOL_GPL(rust_helper_BUG);
 
+void rust_helper_mutex_lock(struct mutex *lock)
+{
+	mutex_lock(lock);
+}
+EXPORT_SYMBOL_GPL(rust_helper_mutex_lock);
+
 refcount_t rust_helper_REFCOUNT_INIT(int n)
 {
 	return (refcount_t)REFCOUNT_INIT(n);
rust/kernel/sync.rs +1 -0
index bf088b324af4..9ff116b2eebe 100644
@@ -11,6 +11,7 @@ mod arc;
 pub mod lock;
 
 pub use arc::{Arc, ArcBorrow, UniqueArc};
+pub use lock::mutex::Mutex;
 
 /// Represents a lockdep class. It's a wrapper around C's `lock_class_key`.
 #[repr(transparent)]
rust/kernel/sync/lock.rs +2 -0
index f5614bed2a78..cec1d68bab86 100644
@@ -10,6 +10,8 @@ use crate::{bindings, init::PinInit, pin_init, str::CStr, types::Opaque};
 use core::{cell::UnsafeCell, marker::PhantomData, marker::PhantomPinned};
 use macros::pin_data;
 
+pub mod mutex;
+
 /// The "backend" of a lock.
 ///
 /// It is the actual implementation of the lock, without the need to repeat patterns used in all
rust/kernel/sync/lock/mutex.rs new file +118 -0

118 lines not on this page · raw message

Signature · 1 line
2.34.1
#3 lore raw

Re: [PATCH v2 03/13] rust: lock: introduce `Mutex`

rust/helpers.c __noreturn void rust_helper_BUG(void) · line 37

Quoted 6 lines · Wedson Almeida Filho
rust/helpers.c +6 -0
+void rust_helper_mutex_lock(struct mutex *lock)
+{
+	mutex_lock(lock);
+}
+EXPORT_SYMBOL_GPL(rust_helper_mutex_lock);
+

No need to ever unlock a mutex?

thanks,

greg k-h

#4 lore raw

Re: [PATCH v2 03/13] rust: lock: introduce `Mutex`

Quoted 9 lines · Greg KH

rust/helpers.c __noreturn void rust_helper_BUG(void) · line 37

Quoted 6 lines · Wedson Almeida Filho
rust/helpers.c +6 -0
+void rust_helper_mutex_lock(struct mutex *lock)
+{
+	mutex_lock(lock);
+}
+EXPORT_SYMBOL_GPL(rust_helper_mutex_lock);
+

No need to ever unlock a mutex?

Oh nevermind, mutex_lock() is a macro, mutex_unlock() is not...

maintainer
#5 lore raw

Re: [PATCH v2 03/13] rust: lock: introduce `Mutex`

Quoted 11 lines · Greg KH
Quoted 9 lines · Greg KH

rust/helpers.c __noreturn void rust_helper_BUG(void) · line 37

Quoted 6 lines · Wedson Almeida Filho
rust/helpers.c +6 -0
+void rust_helper_mutex_lock(struct mutex *lock)
+{
+	mutex_lock(lock);
+}
+EXPORT_SYMBOL_GPL(rust_helper_mutex_lock);
+

No need to ever unlock a mutex?

Quoted 1 line

Oh nevermind, mutex_lock() is a macro, mutex_unlock() is not...

Yeah, so I despise all these stupid helpers... but I suppose it's the best they could come up with to interface the languages :/

The only hope is that the thing can do cross-language LTO or something to re-inline stuff.

#6 lore raw

Re: [PATCH v2 03/13] rust: lock: introduce `Mutex`

Quoted 12 lines · Peter Zijlstra
Quoted 11 lines · Greg KH
Quoted 9 lines · Greg KH

rust/helpers.c __noreturn void rust_helper_BUG(void) · line 37

Quoted 6 lines · Wedson Almeida Filho
rust/helpers.c +6 -0
+void rust_helper_mutex_lock(struct mutex *lock)
+{
+	mutex_lock(lock);
+}
+EXPORT_SYMBOL_GPL(rust_helper_mutex_lock);
+

No need to ever unlock a mutex?

Quoted 7 lines
Quoted 1 line

Oh nevermind, mutex_lock() is a macro, mutex_unlock() is not...

Yeah, so I despise all these stupid helpers... but I suppose it's the best they could come up with to interface the languages :/

The only hope is that the thing can do cross-language LTO or something to re-inline stuff.

One thing we could to do improve the situation is to convert some of the existing macros into inline functions on the header files.

We can't do it for all cases (e.g., cases like mutex_init that declare a new static variable when lockdep is enabled) but mutex_lock is just a function when lockdep is disabled, and just calls mutex_lock_nested() when it is enabled.

How do you feel about this?

-#define mutex_lock(lock) mutex_lock_nested(lock, 0) +static inline void mutex_lock(struct mutex *lock) +{
+ mutex_lock_nested(lock, 0);
+}
+

maintainer
#7 lore raw

Re: [PATCH v2 03/13] rust: lock: introduce `Mutex`

Quoted 30 lines · Wedson Almeida Filho
Quoted 12 lines · Peter Zijlstra
Quoted 11 lines · Greg KH
Quoted 9 lines · Greg KH

rust/helpers.c __noreturn void rust_helper_BUG(void) · line 37

Quoted 6 lines · Wedson Almeida Filho
rust/helpers.c +6 -0
+void rust_helper_mutex_lock(struct mutex *lock)
+{
+	mutex_lock(lock);
+}
+EXPORT_SYMBOL_GPL(rust_helper_mutex_lock);
+

No need to ever unlock a mutex?

Quoted 7 lines
Quoted 1 line

Oh nevermind, mutex_lock() is a macro, mutex_unlock() is not...

Yeah, so I despise all these stupid helpers... but I suppose it's the best they could come up with to interface the languages :/

The only hope is that the thing can do cross-language LTO or something to re-inline stuff.

One thing we could to do improve the situation is to convert some of the existing macros into inline functions on the header files.

We can't do it for all cases (e.g., cases like mutex_init that declare a new static variable when lockdep is enabled) but mutex_lock is just a function when lockdep is disabled, and just calls mutex_lock_nested() when it is enabled.

How do you feel about this?

Review

Quoted 5 lines
(quoted diff) +4 -1
-#define mutex_lock(lock) mutex_lock_nested(lock, 0)
+static inline void mutex_lock(struct mutex *lock)
+{
+       mutex_lock_nested(lock, 0);
+}

Can rust actually parse C headers and inline C functions ? I thought the whole problem was that it can only call C ABI symbols (which inline functions are not).

#8 lore raw

Re: [PATCH v2 03/13] rust: lock: introduce `Mutex`

Quoted 31 lines · Peter Zijlstra
Quoted 30 lines · Wedson Almeida Filho
Quoted 12 lines · Peter Zijlstra
Quoted 11 lines · Greg KH
Quoted 9 lines · Greg KH

rust/helpers.c __noreturn void rust_helper_BUG(void) · line 37

Quoted 6 lines · Wedson Almeida Filho
rust/helpers.c +6 -0
+void rust_helper_mutex_lock(struct mutex *lock)
+{
+	mutex_lock(lock);
+}
+EXPORT_SYMBOL_GPL(rust_helper_mutex_lock);
+

No need to ever unlock a mutex?

Quoted 7 lines
Quoted 1 line

Oh nevermind, mutex_lock() is a macro, mutex_unlock() is not...

Yeah, so I despise all these stupid helpers... but I suppose it's the best they could come up with to interface the languages :/

The only hope is that the thing can do cross-language LTO or something to re-inline stuff.

One thing we could to do improve the situation is to convert some of the existing macros into inline functions on the header files.

We can't do it for all cases (e.g., cases like mutex_init that declare a new static variable when lockdep is enabled) but mutex_lock is just a function when lockdep is disabled, and just calls mutex_lock_nested() when it is enabled.

How do you feel about this?

Quoted 9 lines

Review

Quoted 5 lines
(quoted diff) +4 -1
-#define mutex_lock(lock) mutex_lock_nested(lock, 0)
+static inline void mutex_lock(struct mutex *lock)
+{
+       mutex_lock_nested(lock, 0);
+}

Can rust actually parse C headers and inline C functions ? I thought the whole problem was that it can only call C ABI symbols (which inline functions are not).

Rust can't. We use a tool called bindgen to read C header files and generate equivalent Rust (extern "C") declarations for functions. The tool has been enhanced recently (https://github.com/rust-lang/rust-bindgen/pull/2335) to handle static inline functions by automatically generating helpers like the one above (in addition to the Rust decls).

So the situation is improved in that we don't need to manually write (and commit) the helpers. It may improve further in the future if we get better integration of the languages.

maintainer
#9 lore raw

Re: [PATCH v2 03/13] rust: lock: introduce `Mutex`

Quoted 42 lines · Wedson Almeida Filho
Quoted 31 lines · Peter Zijlstra
Quoted 30 lines · Wedson Almeida Filho
Quoted 12 lines · Peter Zijlstra
Quoted 11 lines · Greg KH
Quoted 9 lines · Greg KH

Review

Quoted 6 lines · Wedson Almeida Filho
(quoted diff) +6 -0
+void rust_helper_mutex_lock(struct mutex *lock)
+{
+	mutex_lock(lock);
+}
+EXPORT_SYMBOL_GPL(rust_helper_mutex_lock);
+

No need to ever unlock a mutex?

Quoted 7 lines
Quoted 1 line

Oh nevermind, mutex_lock() is a macro, mutex_unlock() is not...

Yeah, so I despise all these stupid helpers... but I suppose it's the best they could come up with to interface the languages :/

The only hope is that the thing can do cross-language LTO or something to re-inline stuff.

One thing we could to do improve the situation is to convert some of the existing macros into inline functions on the header files.

We can't do it for all cases (e.g., cases like mutex_init that declare a new static variable when lockdep is enabled) but mutex_lock is just a function when lockdep is disabled, and just calls mutex_lock_nested() when it is enabled.

How do you feel about this?

Quoted 9 lines

Review

Quoted 5 lines
(quoted diff) +4 -1
-#define mutex_lock(lock) mutex_lock_nested(lock, 0)
+static inline void mutex_lock(struct mutex *lock)
+{
+       mutex_lock_nested(lock, 0);
+}

Can rust actually parse C headers and inline C functions ? I thought the whole problem was that it can only call C ABI symbols (which inline functions are not).

Quoted 5 lines

Rust can't. We use a tool called bindgen to read C header files and generate equivalent Rust (extern "C") declarations for functions. The tool has been enhanced recently (https://github.com/rust-lang/rust-bindgen/pull/2335) to handle static inline functions by automatically generating helpers like the one above (in addition to the Rust decls).

Oh man, that's sad, I was hoping it would write the equivalent inline function in rust.

Quoted 3 lines

So the situation is improved in that we don't need to manually write (and commit) the helpers. It may improve further in the future if we get better integration of the languages.

But yeah, feel free to convert macros to inline functions where the difference is moot. There is indeed no real reason for mutex_lock() to not be an inline function in that case.

#10 lore raw

RE: [PATCH v2 03/13] rust: lock: introduce `Mutex`

From: Peter Zijlstra

Quoted 3 lines

Sent: 05 April 2023 21:50

On Wed, Apr 05, 2023 at 05:40:39PM -0300, Wedson Almeida Filho wrote:

...

Quoted 7 lines
Quoted 3 lines

So the situation is improved in that we don't need to manually write (and commit) the helpers. It may improve further in the future if we get better integration of the languages.

But yeah, feel free to convert macros to inline functions where the difference is moot. There is indeed no real reason for mutex_lock() to not be an inline function in that case.

mutex_lock() is probably ok.
But there are cases where gcc generates much better code for #defines than for inline functions.
Almost certainly because the front end gets to optimise #defines, but inlines are done much later on.

David

-
Registered Address Lakeside, Bramley Road, Mount Farm, Milton Keynes, MK1 1PT, UK Registration No: 1397386 (Wales)

#11 lore raw

Re: [PATCH v2 03/13] rust: lock: introduce `Mutex`

Quoted 14 lines · David Laight

From: Peter Zijlstra

Quoted 3 lines

Sent: 05 April 2023 21:50

On Wed, Apr 05, 2023 at 05:40:39PM -0300, Wedson Almeida Filho wrote:

...

Quoted 7 lines
Quoted 3 lines

So the situation is improved in that we don't need to manually write (and commit) the helpers. It may improve further in the future if we get better integration of the languages.

But yeah, feel free to convert macros to inline functions where the difference is moot. There is indeed no real reason for mutex_lock() to not be an inline function in that case.

Quoted 5 lines

mutex_lock() is probably ok.
But there are cases where gcc generates much better code for #defines than for inline functions.
Almost certainly because the front end gets to optimise #defines, but inlines are done much later on.

For macro to inline function conversions, the most conservative option would be __always_inline. We've also seen things go wrong with "inline" only paired with various kinds of instrumentation.

Can bindgen deal with "static __always_inline" functions?

#12 lore raw

Re: [PATCH v2 03/13] rust: lock: introduce `Mutex`

Quoted 6 lines · Marco Elver

For macro to inline function conversions, the most conservative option would be __always_inline. We've also seen things go wrong with "inline" only paired with various kinds of instrumentation.

Can bindgen deal with "static __always_inline" functions?

If you mean the new feature where bindgen generates wrappers automatically, it seems to handle them given __always_inline => inline which is what I imagine it looks for (I assume it does not care about the actual attribute), though I haven't tried to use the feature within the kernel yet.

Cheers,
Miguel

#13 lore raw

Re: [PATCH v2 03/13] rust: lock: introduce `Mutex`

In reply to Peter Zijlstra
Quoted 3 lines · Peter Zijlstra

Oh man, that's sad, I was hoping it would write the equivalent inline function in rust.

Some of us hope Rust would directly handle importing C headers, so avoiding the intermediate step, like a few languages support.

Quoted 3 lines

But yeah, feel free to convert macros to inline functions where the difference is moot. There is indeed no real reason for mutex_lock() to not be an inline function in that case.

We initially minimized changes on the C side on purpose, but if maintainers are OK with that (modulo exceptions), it would be great.

Cheers,
Miguel

#14 lore raw

PATCH v2 4/13 locking/spinlock: introduce spin_lock_init_with_key

In reply to Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

Rust cannot call C macros, so it has its own macro to create a new lock class when a spin lock is initialised. This new function allows Rust code to pass the lock class it generates to the C implementation.

Cc Peter Zijlstra <[email protected]>
Cc Ingo Molnar <[email protected]>
Cc Will Deacon <[email protected]>
Cc Waiman Long <[email protected]>

---
v1 -> v2: No changes

 include/linux/spinlock.h | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)
include/linux/spinlock.h +7 -2
index be48f1cb1878..cdc92d095133 100644
@@ -327,12 +327,17 @@ static __always_inline raw_spinlock_t *spinlock_check(spinlock_t *lock)
 
 #ifdef CONFIG_DEBUG_SPINLOCK
 
+static inline void spin_lock_init_with_key(spinlock_t *lock, const char *name,
+					   struct lock_class_key *key)
+{
+	__raw_spin_lock_init(spinlock_check(lock), name, key, LD_WAIT_CONFIG);
+}
+
 # define spin_lock_init(lock)					\
 do {								\
 	static struct lock_class_key __key;			\
 								\
-	__raw_spin_lock_init(spinlock_check(lock),		\
-			     #lock, &__key, LD_WAIT_CONFIG);	\
+	spin_lock_init_with_key(lock, #lock, &__key);		\
 } while (0)
 
 #else
Signature · 1 line
2.34.1
#15 lore raw

PATCH v2 5/13 rust: lock: introduce `SpinLock`

In reply to Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This is the spinlock_t lock backend and allows Rust code to use the kernel spinlock idiomatically.

Cc Peter Zijlstra <[email protected]>
Cc Ingo Molnar <[email protected]>
Cc Will Deacon <[email protected]>
Cc Waiman Long <[email protected]>

---
v1 -> v2: No changes

 rust/helpers.c                    |  24 +++++++
 rust/kernel/sync.rs               |   2 +-
 rust/kernel/sync/lock.rs          |   1 +
 rust/kernel/sync/lock/spinlock.rs | 116 ++++++++++++++++++++++++++++++
 4 files changed, 142 insertions(+), 1 deletion(-)
 create mode 100644 rust/kernel/sync/lock/spinlock.rs
rust/helpers.c +24 -0
index 3010a2ec26e2..05694e3f8f70 100644
@@ -22,6 +22,7 @@
 #include <linux/build_bug.h>
 #include <linux/refcount.h>
 #include <linux/mutex.h>
+#include <linux/spinlock.h>
 
 __noreturn void rust_helper_BUG(void)
 {
@@ -35,6 +36,29 @@ void rust_helper_mutex_lock(struct mutex *lock)
 }
 EXPORT_SYMBOL_GPL(rust_helper_mutex_lock);
 
+void rust_helper___spin_lock_init(spinlock_t *lock, const char *name,
+				  struct lock_class_key *key)
+{
+#ifdef CONFIG_DEBUG_SPINLOCK
+	spin_lock_init_with_key(lock, name, key);
+#else
+	spin_lock_init(lock);
+#endif
+}
+EXPORT_SYMBOL_GPL(rust_helper___spin_lock_init);
+
+void rust_helper_spin_lock(spinlock_t *lock)
+{
+	spin_lock(lock);
+}
+EXPORT_SYMBOL_GPL(rust_helper_spin_lock);
+
+void rust_helper_spin_unlock(spinlock_t *lock)
+{
+	spin_unlock(lock);
+}
+EXPORT_SYMBOL_GPL(rust_helper_spin_unlock);
+
 refcount_t rust_helper_REFCOUNT_INIT(int n)
 {
 	return (refcount_t)REFCOUNT_INIT(n);
rust/kernel/sync.rs +1 -1
index 9ff116b2eebe..ed07437d7d55 100644
@@ -11,7 +11,7 @@ mod arc;
 pub mod lock;
 
 pub use arc::{Arc, ArcBorrow, UniqueArc};
-pub use lock::mutex::Mutex;
+pub use lock::{mutex::Mutex, spinlock::SpinLock};
 
 /// Represents a lockdep class. It's a wrapper around C's `lock_class_key`.
 #[repr(transparent)]
rust/kernel/sync/lock.rs +1 -0
index cec1d68bab86..bca9af2a9a5a 100644
@@ -11,6 +11,7 @@ use core::{cell::UnsafeCell, marker::PhantomData, marker::PhantomPinned};
 use macros::pin_data;
 
 pub mod mutex;
+pub mod spinlock;
 
 /// The "backend" of a lock.
 ///
rust/kernel/sync/lock/spinlock.rs new file +116 -0

116 lines not on this page · raw message

Signature · 1 line
2.34.1
#16 lore raw

PATCH v2 6/13 rust: lock: add support for `Lock::lock_irqsave`

In reply to Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This allows locks like spinlocks and raw spinlocks to expose a lock_irqsave variant in Rust that corresponds to the C version.

---
v1 -> v2: No changes

 rust/kernel/sync/lock.rs | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)
rust/kernel/sync/lock.rs +38 -0
index bca9af2a9a5a..491446c3a074 100644
@@ -57,6 +57,29 @@ pub unsafe trait Backend {
     unsafe fn unlock(ptr: *mut Self::State, guard_state: &Self::GuardState);
 }
 
+/// The "backend" of a lock that supports the irq-save variant.
+///
+/// # Safety
+///
+/// The same requirements wrt mutual exclusion in [`Backend`] apply for acquiring the lock via
+/// [`IrqSaveBackend::lock_irqsave`].
+///
+/// Additionally, when [`IrqSaveBackend::lock_irqsave`] is used to acquire the lock, implementers
+/// must disable interrupts on lock, and restore interrupt state on unlock. Implementers may use
+/// [`Backend::GuardState`] to store state needed to keep track of the interrupt state.
+pub unsafe trait IrqSaveBackend: Backend {
+    /// Acquires the lock, making the caller its owner.
+    ///
+    /// Before acquiring the lock, it disables interrupts, and returns the previous interrupt state
+    /// as its guard state so that the guard can restore it when it is dropped.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that [`Backend::init`] has been previously called.
+    #[must_use]
+    unsafe fn lock_irqsave(ptr: *mut Self::State) -> Self::GuardState;
+}
+
 /// A mutual exclusion primitive.
 ///
 /// Exposes one of the kernel locking primitives. Which one is exposed depends on the lock banckend
@@ -109,6 +132,21 @@ impl<T: ?Sized, B: Backend> Lock<T, B> {
     }
 }
 
+impl<T: ?Sized, B: IrqSaveBackend> Lock<T, B> {
+    /// Acquires the lock and gives the caller access to the data protected by it.
+    ///
+    /// Before acquiring the lock, it disables interrupts. When the guard is dropped, the interrupt
+    /// state (either enabled or disabled) is restored to its state before
+    /// [`lock_irqsave`](Self::lock_irqsave) was called.
+    pub fn lock_irqsave(&self) -> Guard<'_, T, B> {
+        // SAFETY: The constructor of the type calls `init`, so the existence of the object proves
+        // that `init` was called.
+        let state = unsafe { B::lock_irqsave(self.state.get()) };
+        // SAFETY: The lock was just acquired.
+        unsafe { Guard::new(self, state) }
+    }
+}
+
 /// A lock guard.
 ///
 /// Allows mutual exclusion primitives that implement the `Backend` trait to automatically unlock
Signature · 1 line
2.34.1
#17 lore raw

PATCH v2 7/13 rust: lock: implement `IrqSaveBackend` for `SpinLock`

In reply to Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This allows Rust code to use the lock_irqsave variant of spinlocks.

Cc Peter Zijlstra <[email protected]>
Cc Ingo Molnar <[email protected]>
Cc Will Deacon <[email protected]>
Cc Waiman Long <[email protected]>

---
v1 -> v2: No changes

 rust/helpers.c                    | 16 +++++++++++++
 rust/kernel/sync/lock/spinlock.rs | 38 ++++++++++++++++++++++++++-----
 2 files changed, 48 insertions(+), 6 deletions(-)
rust/helpers.c +16 -0
index 05694e3f8f70..e42f5b446f92 100644
@@ -59,6 +59,22 @@ void rust_helper_spin_unlock(spinlock_t *lock)
 }
 EXPORT_SYMBOL_GPL(rust_helper_spin_unlock);
 
+unsigned long rust_helper_spin_lock_irqsave(spinlock_t *lock)
+{
+	unsigned long flags;
+
+	spin_lock_irqsave(lock, flags);
+
+	return flags;
+}
+EXPORT_SYMBOL_GPL(rust_helper_spin_lock_irqsave);
+
+void rust_helper_spin_unlock_irqrestore(spinlock_t *lock, unsigned long flags)
+{
+	spin_unlock_irqrestore(lock, flags);
+}
+EXPORT_SYMBOL_GPL(rust_helper_spin_unlock_irqrestore);
+
 refcount_t rust_helper_REFCOUNT_INIT(int n)
 {
 	return (refcount_t)REFCOUNT_INIT(n);
rust/kernel/sync/lock/spinlock.rs +32 -6
index a52d20fc9755..34dec09a97c0 100644
@@ -61,6 +61,8 @@ macro_rules! new_spinlock {
 /// assert_eq!(e.c, 10);
 /// assert_eq!(e.d.lock().a, 20);
 /// assert_eq!(e.d.lock().b, 30);
+/// assert_eq!(e.d.lock_irqsave().a, 20);
+/// assert_eq!(e.d.lock_irqsave().b, 30);
 /// ```
 ///
 /// The following example shows how to use interior mutability to modify the contents of a struct
@@ -79,6 +81,12 @@ macro_rules! new_spinlock {
 ///     guard.a += 10;
 ///     guard.b += 20;
 /// }
+///
+/// fn example2(m: &SpinLock<Example>) {
+///     let mut guard = m.lock_irqsave();
+///     guard.a += 10;
+///     guard.b += 20;
+/// }
 /// ```
 ///
 /// [`spinlock_t`]: ../../../../include/linux/spinlock.h
@@ -90,7 +98,7 @@ pub struct SpinLockBackend;
 // SAFETY: The underlying kernel `spinlock_t` object ensures mutual exclusion.
 unsafe impl super::Backend for SpinLockBackend {
     type State = bindings::spinlock_t;
-    type GuardState = ();
+    type GuardState = Option<core::ffi::c_ulong>;
 
     unsafe fn init(
         ptr: *mut Self::State,
@@ -105,12 +113,30 @@ unsafe impl super::Backend for SpinLockBackend {
     unsafe fn lock(ptr: *mut Self::State) -> Self::GuardState {
         // SAFETY: The safety requirements of this function ensure that `ptr` points to valid
         // memory, and that it has been initialised before.
-        unsafe { bindings::spin_lock(ptr) }
+        unsafe { bindings::spin_lock(ptr) };
+        None
     }
 
-    unsafe fn unlock(ptr: *mut Self::State, _guard_state: &Self::GuardState) {
-        // SAFETY: The safety requirements of this function ensure that `ptr` is valid and that the
-        // caller is the owner of the mutex.
-        unsafe { bindings::spin_unlock(ptr) }
+    unsafe fn unlock(ptr: *mut Self::State, guard_state: &Self::GuardState) {
+        match guard_state {
+            // SAFETY: The safety requirements of this function ensure that `ptr` is valid and that
+            // the caller is the owner of the mutex.
+            Some(flags) => unsafe { bindings::spin_unlock_irqrestore(ptr, *flags) },
+            // SAFETY: The safety requirements of this function ensure that `ptr` is valid and that
+            // the caller is the owner of the mutex.
+            None => unsafe { bindings::spin_unlock(ptr) },
+        }
+    }
+}
+
+// SAFETY: The underlying kernel `spinlock_t` object ensures mutual exclusion. We use the `irqsave`
+// variant of the C lock acquisition functions to disable interrupts and retrieve the original
+// interrupt state, and the `irqrestore` variant of the lock release functions to restore the state
+// in `unlock` -- we use the guard context to determine which method was used to acquire the lock.
+unsafe impl super::IrqSaveBackend for SpinLockBackend {
+    unsafe fn lock_irqsave(ptr: *mut Self::State) -> Self::GuardState {
+        // SAFETY: The safety requirements of this function ensure that `ptr` points to valid
+        // memory, and that it has been initialised before.
+        Some(unsafe { bindings::spin_lock_irqsave(ptr) })
     }
 }
Signature · 1 line
2.34.1
#18 lore raw

PATCH v2 8/13 rust: introduce `ARef`

In reply to Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This is an owned reference to an object that is always ref-counted. This is meant to be used in wrappers for C types that have their own ref counting functions, for example, tasks, files, inodes, dentries, etc.

---
v1 -> v2: No changes

 rust/kernel/types.rs | 107 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)
rust/kernel/types.rs +107 -0
index dbfae9bb97ce..b071730253c7 100644
@@ -6,8 +6,10 @@ use crate::init::{self, PinInit};
 use alloc::boxed::Box;
 use core::{
     cell::UnsafeCell,
+    marker::PhantomData,
     mem::MaybeUninit,
     ops::{Deref, DerefMut},
+    ptr::NonNull,
 };
 
 /// Used to transfer ownership to and from foreign (non-Rust) languages.
@@ -295,6 +297,111 @@ opaque_init_funcs! {
     "Rust" manual_init4(arg1: A1, arg2: A2, arg3: A3, arg4: A4);
 }
 
+/// Types that are _always_ reference counted.
+///
+/// It allows such types to define their own custom ref increment and decrement functions.
+/// Additionally, it allows users to convert from a shared reference `&T` to an owned reference
+/// [`ARef<T>`].
+///
+/// This is usually implemented by wrappers to existing structures on the C side of the code. For
+/// Rust code, the recommendation is to use [`Arc`](crate::sync::Arc) to create reference-counted
+/// instances of a type.
+///
+/// # Safety
+///
+/// Implementers must ensure that increments to the reference count keep the object alive in memory
+/// at least until matching decrements are performed.
+///
+/// Implementers must also ensure that all instances are reference-counted. (Otherwise they
+/// won't be able to honour the requirement that [`AlwaysRefCounted::inc_ref`] keep the object
+/// alive.)
+pub unsafe trait AlwaysRefCounted {
+    /// Increments the reference count on the object.
+    fn inc_ref(&self);
+
+    /// Decrements the reference count on the object.
+    ///
+    /// Frees the object when the count reaches zero.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that there was a previous matching increment to the reference count,
+    /// and that the object is no longer used after its reference count is decremented (as it may
+    /// result in the object being freed), unless the caller owns another increment on the refcount
+    /// (e.g., it calls [`AlwaysRefCounted::inc_ref`] twice, then calls
+    /// [`AlwaysRefCounted::dec_ref`] once).
+    unsafe fn dec_ref(obj: NonNull<Self>);
+}
+
+/// An owned reference to an always-reference-counted object.
+///
+/// The object's reference count is automatically decremented when an instance of [`ARef`] is
+/// dropped. It is also automatically incremented when a new instance is created via
+/// [`ARef::clone`].
+///
+/// # Invariants
+///
+/// The pointer stored in `ptr` is non-null and valid for the lifetime of the [`ARef`] instance. In
+/// particular, the [`ARef`] instance owns an increment on the underlying object's reference count.
+pub struct ARef<T: AlwaysRefCounted> {
+    ptr: NonNull<T>,
+    _p: PhantomData<T>,
+}
+
+impl<T: AlwaysRefCounted> ARef<T> {
+    /// Creates a new instance of [`ARef`].
+    ///
+    /// It takes over an increment of the reference count on the underlying object.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that the reference count was incremented at least once, and that they
+    /// are properly relinquishing one increment. That is, if there is only one increment, callers
+    /// must not use the underlying object anymore -- it is only safe to do so via the newly
+    /// created [`ARef`].
+    pub unsafe fn from_raw(ptr: NonNull<T>) -> Self {
+        // INVARIANT: The safety requirements guarantee that the new instance now owns the
+        // increment on the refcount.
+        Self {
+            ptr,
+            _p: PhantomData,
+        }
+    }
+}
+
+impl<T: AlwaysRefCounted> Clone for ARef<T> {
+    fn clone(&self) -> Self {
+        self.inc_ref();
+        // SAFETY: We just incremented the refcount above.
+        unsafe { Self::from_raw(self.ptr) }
+    }
+}
+
+impl<T: AlwaysRefCounted> Deref for ARef<T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        // SAFETY: The type invariants guarantee that the object is valid.
+        unsafe { self.ptr.as_ref() }
+    }
+}
+
+impl<T: AlwaysRefCounted> From<&T> for ARef<T> {
+    fn from(b: &T) -> Self {
+        b.inc_ref();
+        // SAFETY: We just incremented the refcount above.
+        unsafe { Self::from_raw(NonNull::from(b)) }
+    }
+}
+
+impl<T: AlwaysRefCounted> Drop for ARef<T> {
+    fn drop(&mut self) {
+        // SAFETY: The type invariants guarantee that the `ARef` owns the reference we're about to
+        // decrement.
+        unsafe { T::dec_ref(self.ptr) };
+    }
+}
+
 /// A sum type that always holds either a value of type `L` or `R`.
 pub enum Either<L, R> {
     /// Constructs an instance of [`Either`] containing a value of type `L`.
Signature · 1 line
2.34.1
#19 lore raw

Re: [PATCH v2 08/13] rust: introduce `ARef`

Quoted 84 lines · Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This is an owned reference to an object that is always ref-counted. This is meant to be used in wrappers for C types that have their own ref counting functions, for example, tasks, files, inodes, dentries, etc.

---
v1 -> v2: No changes

  rust/kernel/types.rs | 107 +++++++++++++++++++++++++++++++++++++++++++
  1 file changed, 107 insertions(+)
rust/kernel/types.rs +54 -0
index dbfae9bb97ce..b071730253c7 100644
@@ -6,8 +6,10 @@ use crate::init::{self, PinInit};
  use alloc::boxed::Box;
  use core::{
      cell::UnsafeCell,
+    marker::PhantomData,
      mem::MaybeUninit,
      ops::{Deref, DerefMut},
+    ptr::NonNull,
  };
 
  /// Used to transfer ownership to and from foreign (non-Rust) languages.
@@ -295,6 +297,111 @@ opaque_init_funcs! {
      "Rust" manual_init4(arg1: A1, arg2: A2, arg3: A3, arg4: A4);
  }
 
+/// Types that are _always_ reference counted.
+///
+/// It allows such types to define their own custom ref increment and decrement functions.
+/// Additionally, it allows users to convert from a shared reference `&T` to an owned reference
+/// [`ARef<T>`].
+///
+/// This is usually implemented by wrappers to existing structures on the C side of the code. For
+/// Rust code, the recommendation is to use [`Arc`](crate::sync::Arc) to create reference-counted
+/// instances of a type.
+///
+/// # Safety
+///
+/// Implementers must ensure that increments to the reference count keep the object alive in memory
+/// at least until matching decrements are performed.
+///
+/// Implementers must also ensure that all instances are reference-counted. (Otherwise they
+/// won't be able to honour the requirement that [`AlwaysRefCounted::inc_ref`] keep the object
+/// alive.)
+pub unsafe trait AlwaysRefCounted {
+    /// Increments the reference count on the object.
+    fn inc_ref(&self);
+
+    /// Decrements the reference count on the object.
+    ///
+    /// Frees the object when the count reaches zero.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that there was a previous matching increment to the reference count,
+    /// and that the object is no longer used after its reference count is decremented (as it may
+    /// result in the object being freed), unless the caller owns another increment on the refcount
+    /// (e.g., it calls [`AlwaysRefCounted::inc_ref`] twice, then calls
+    /// [`AlwaysRefCounted::dec_ref`] once).
+    unsafe fn dec_ref(obj: NonNull<Self>);
+}
+
+/// An owned reference to an always-reference-counted object.
+///
+/// The object's reference count is automatically decremented when an instance of [`ARef`] is
+/// dropped. It is also automatically incremented when a new instance is created via
+/// [`ARef::clone`].
+///
+/// # Invariants
+///
+/// The pointer stored in `ptr` is non-null and valid for the lifetime of the [`ARef`] instance. In
+/// particular, the [`ARef`] instance owns an increment on the underlying object's reference count.
+pub struct ARef<T: AlwaysRefCounted> {
+    ptr: NonNull<T>,
+    _p: PhantomData<T>,
+}
+
+impl<T: AlwaysRefCounted> ARef<T> {

rust/kernel/types.rs opaque_init_funcs! { · line 361

Quoted 10 lines
rust/kernel/types.rs +10 -0
+    /// Creates a new instance of [`ARef`].
+    ///
+    /// It takes over an increment of the reference count on the underlying object.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that the reference count was incremented at least once, and that they
+    /// are properly relinquishing one increment. That is, if there is only one increment, callers
+    /// must not use the underlying object anymore -- it is only safe to do so via the newly
+    /// created [`ARef`].

I think you should also mention that the pointee at ptr must live at least until this ARef decides to decrement the refcount. Otherwise I would interpret the docs as written to allow you to give a pointer to the stack and then free the backing storage and then continue to use the ARef.

--
Cheers,
Benno

Quoted 49 lines
rust/kernel/types.rs +43 -1
+    pub unsafe fn from_raw(ptr: NonNull<T>) -> Self {
+        // INVARIANT: The safety requirements guarantee that the new instance now owns the
+        // increment on the refcount.
+        Self {
+            ptr,
+            _p: PhantomData,
+        }
+    }
+}
+
+impl<T: AlwaysRefCounted> Clone for ARef<T> {
+    fn clone(&self) -> Self {
+        self.inc_ref();
+        // SAFETY: We just incremented the refcount above.
+        unsafe { Self::from_raw(self.ptr) }
+    }
+}
+
+impl<T: AlwaysRefCounted> Deref for ARef<T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        // SAFETY: The type invariants guarantee that the object is valid.
+        unsafe { self.ptr.as_ref() }
+    }
+}
+
+impl<T: AlwaysRefCounted> From<&T> for ARef<T> {
+    fn from(b: &T) -> Self {
+        b.inc_ref();
+        // SAFETY: We just incremented the refcount above.
+        unsafe { Self::from_raw(NonNull::from(b)) }
+    }
+}
+
+impl<T: AlwaysRefCounted> Drop for ARef<T> {
+    fn drop(&mut self) {
+        // SAFETY: The type invariants guarantee that the `ARef` owns the reference we're about to
+        // decrement.
+        unsafe { T::dec_ref(self.ptr) };
+    }
+}
+
  /// A sum type that always holds either a value of type `L` or `R`.
  pub enum Either<L, R> {
      /// Constructs an instance of [`Either`] containing a value of type `L`.
--

2.34.1

#20 lore raw

Re: [PATCH v2 08/13] rust: introduce `ARef`

Quoted 94 lines · Benno Lossin
Quoted 92 lines · Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This is an owned reference to an object that is always ref-counted. This is meant to be used in wrappers for C types that have their own ref counting functions, for example, tasks, files, inodes, dentries, etc.

---
v1 -> v2: No changes

  rust/kernel/types.rs | 107 +++++++++++++++++++++++++++++++++++++++++++
  1 file changed, 107 insertions(+)
rust/kernel/types.rs +62 -0
index dbfae9bb97ce..b071730253c7 100644
@@ -6,8 +6,10 @@ use crate::init::{self, PinInit};
  use alloc::boxed::Box;
  use core::{
      cell::UnsafeCell,
+    marker::PhantomData,
      mem::MaybeUninit,
      ops::{Deref, DerefMut},
+    ptr::NonNull,
  };
 
  /// Used to transfer ownership to and from foreign (non-Rust) languages.
@@ -295,6 +297,111 @@ opaque_init_funcs! {
      "Rust" manual_init4(arg1: A1, arg2: A2, arg3: A3, arg4: A4);
  }
 
+/// Types that are _always_ reference counted.
+///
+/// It allows such types to define their own custom ref increment and decrement functions.
+/// Additionally, it allows users to convert from a shared reference `&T` to an owned reference
+/// [`ARef<T>`].
+///
+/// This is usually implemented by wrappers to existing structures on the C side of the code. For
+/// Rust code, the recommendation is to use [`Arc`](crate::sync::Arc) to create reference-counted
+/// instances of a type.
+///
+/// # Safety
+///
+/// Implementers must ensure that increments to the reference count keep the object alive in memory
+/// at least until matching decrements are performed.
+///
+/// Implementers must also ensure that all instances are reference-counted. (Otherwise they
+/// won't be able to honour the requirement that [`AlwaysRefCounted::inc_ref`] keep the object
+/// alive.)
+pub unsafe trait AlwaysRefCounted {
+    /// Increments the reference count on the object.
+    fn inc_ref(&self);
+
+    /// Decrements the reference count on the object.
+    ///
+    /// Frees the object when the count reaches zero.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that there was a previous matching increment to the reference count,
+    /// and that the object is no longer used after its reference count is decremented (as it may
+    /// result in the object being freed), unless the caller owns another increment on the refcount
+    /// (e.g., it calls [`AlwaysRefCounted::inc_ref`] twice, then calls
+    /// [`AlwaysRefCounted::dec_ref`] once).
+    unsafe fn dec_ref(obj: NonNull<Self>);
+}
+
+/// An owned reference to an always-reference-counted object.
+///
+/// The object's reference count is automatically decremented when an instance of [`ARef`] is
+/// dropped. It is also automatically incremented when a new instance is created via
+/// [`ARef::clone`].
+///
+/// # Invariants
+///
+/// The pointer stored in `ptr` is non-null and valid for the lifetime of the [`ARef`] instance. In
+/// particular, the [`ARef`] instance owns an increment on the underlying object's reference count.
+pub struct ARef<T: AlwaysRefCounted> {
+    ptr: NonNull<T>,
+    _p: PhantomData<T>,
+}
+
+impl<T: AlwaysRefCounted> ARef<T> {
+    /// Creates a new instance of [`ARef`].
+    ///
+    /// It takes over an increment of the reference count on the underlying object.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that the reference count was incremented at least once, and that they
+    /// are properly relinquishing one increment. That is, if there is only one increment, callers
Quoted 8 lines

rust/kernel/types.rs opaque_init_funcs! { · line 361

Quoted 2 lines
rust/kernel/types.rs +2 -0
+    /// must not use the underlying object anymore -- it is only safe to do so via the newly
+    /// created [`ARef`].

I think you should also mention that the pointee at ptr must live at least until this ARef decides to decrement the refcount. Otherwise I would interpret the docs as written to allow you to give a pointer to the stack and then free the backing storage and then continue to use the ARef.

Note the bound T: AlwaysRefCounted. AlwaysRefCounted is unsafe and has the following requirements:

// Implementers must ensure that increments to the reference count keep the object alive in memory
// at least until matching decrements are performed. ///
/// Implementers must also ensure that all instances are reference-counted. (Otherwise they
/// won't be able to honour the requirement that [AlwaysRefCounted::inc_ref] keep the object
/// alive.)

The latter guarantees that _all_ instances are refcounted. While the former guarantees that you can only free an instance when the refcount goes to zero.

The safety requirement of the function ensures that the caller is donating an increment to ARef.

So it's ok to allocate from the stack. But you cannot free it immediately without violating some promise you must abide by for safety.

Quoted 55 lines

--
Cheers,
Benno

Quoted 49 lines
rust/kernel/types.rs +43 -1
+    pub unsafe fn from_raw(ptr: NonNull<T>) -> Self {
+        // INVARIANT: The safety requirements guarantee that the new instance now owns the
+        // increment on the refcount.
+        Self {
+            ptr,
+            _p: PhantomData,
+        }
+    }
+}
+
+impl<T: AlwaysRefCounted> Clone for ARef<T> {
+    fn clone(&self) -> Self {
+        self.inc_ref();
+        // SAFETY: We just incremented the refcount above.
+        unsafe { Self::from_raw(self.ptr) }
+    }
+}
+
+impl<T: AlwaysRefCounted> Deref for ARef<T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        // SAFETY: The type invariants guarantee that the object is valid.
+        unsafe { self.ptr.as_ref() }
+    }
+}
+
+impl<T: AlwaysRefCounted> From<&T> for ARef<T> {
+    fn from(b: &T) -> Self {
+        b.inc_ref();
+        // SAFETY: We just incremented the refcount above.
+        unsafe { Self::from_raw(NonNull::from(b)) }
+    }
+}
+
+impl<T: AlwaysRefCounted> Drop for ARef<T> {
+    fn drop(&mut self) {
+        // SAFETY: The type invariants guarantee that the `ARef` owns the reference we're about to
+        // decrement.
+        unsafe { T::dec_ref(self.ptr) };
+    }
+}
+
  /// A sum type that always holds either a value of type `L` or `R`.
  pub enum Either<L, R> {
      /// Constructs an instance of [`Either`] containing a value of type `L`.
--

2.34.1

#21 lore raw

PATCH v2 9/13 rust: add basic `Task`

In reply to Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

It is an abstraction for C's struct task_struct. It implements AlwaysRefCounted, so the refcount of the wrapped object is managed safely on the Rust side.

---
v1 -> v2: No changes

 rust/bindings/bindings_helper.h |  1 +
 rust/helpers.c                  | 19 +++++++++
 rust/kernel/lib.rs              |  1 +
 rust/kernel/task.rs             | 71 +++++++++++++++++++++++++++++++++
 4 files changed, 92 insertions(+)
 create mode 100644 rust/kernel/task.rs
rust/bindings/bindings_helper.h +1 -0
index 75d85bd6c592..03656a44a83f 100644
@@ -8,6 +8,7 @@
 
 #include <linux/slab.h>
 #include <linux/refcount.h>
+#include <linux/sched.h>
 
 /* `bindgen` gets confused at certain things. */
 const gfp_t BINDINGS_GFP_KERNEL = GFP_KERNEL;
rust/helpers.c +19 -0
index e42f5b446f92..58a194042c86 100644
@@ -23,6 +23,7 @@
 #include <linux/refcount.h>
 #include <linux/mutex.h>
 #include <linux/spinlock.h>
+#include <linux/sched/signal.h>
 
 __noreturn void rust_helper_BUG(void)
 {
@@ -75,6 +76,12 @@ void rust_helper_spin_unlock_irqrestore(spinlock_t *lock, unsigned long flags)
 }
 EXPORT_SYMBOL_GPL(rust_helper_spin_unlock_irqrestore);
 
+int rust_helper_signal_pending(struct task_struct *t)
+{
+	return signal_pending(t);
+}
+EXPORT_SYMBOL_GPL(rust_helper_signal_pending);
+
 refcount_t rust_helper_REFCOUNT_INIT(int n)
 {
 	return (refcount_t)REFCOUNT_INIT(n);
@@ -93,6 +100,18 @@ bool rust_helper_refcount_dec_and_test(refcount_t *r)
 }
 EXPORT_SYMBOL_GPL(rust_helper_refcount_dec_and_test);
 
+void rust_helper_get_task_struct(struct task_struct *t)
+{
+	get_task_struct(t);
+}
+EXPORT_SYMBOL_GPL(rust_helper_get_task_struct);
+
+void rust_helper_put_task_struct(struct task_struct *t)
+{
+	put_task_struct(t);
+}
+EXPORT_SYMBOL_GPL(rust_helper_put_task_struct);
+
 /*
  * We use `bindgen`'s `--size_t-is-usize` option to bind the C `size_t` type
  * as the Rust `usize` type, so we can use it in contexts where Rust
rust/kernel/lib.rs +1 -0
index d9df77132fa2..4e1d5ba2e241 100644
@@ -43,6 +43,7 @@ mod static_assert;
 pub mod std_vendor;
 pub mod str;
 pub mod sync;
+pub mod task;
 pub mod types;
 
 #[doc(hidden)]
rust/kernel/task.rs new file +71 -0

71 lines not on this page · raw message

Signature · 1 line
2.34.1
#22 lore raw

PATCH v2 10/13 rust: introduce `current`

In reply to Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This allows Rust code to get a reference to the current task without having to increment the refcount, but still guaranteeing memory safety.

---
v1 -> v2: Make current a macro to prevent it from escaping the caller

 rust/helpers.c         |  6 +++
 rust/kernel/prelude.rs |  2 +
 rust/kernel/task.rs    | 93 +++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 100 insertions(+), 1 deletion(-)
rust/helpers.c +6 -0
index 58a194042c86..96441744030e 100644
@@ -100,6 +100,12 @@ bool rust_helper_refcount_dec_and_test(refcount_t *r)
 }
 EXPORT_SYMBOL_GPL(rust_helper_refcount_dec_and_test);
 
+struct task_struct *rust_helper_get_current(void)
+{
+	return current;
+}
+EXPORT_SYMBOL_GPL(rust_helper_get_current);
+
 void rust_helper_get_task_struct(struct task_struct *t)
 {
 	get_task_struct(t);
rust/kernel/prelude.rs +2 -0
index fcdc511d2ce8..c28587d68ebc 100644
@@ -36,3 +36,5 @@ pub use super::error::{code::*, Error, Result};
 pub use super::{str::CStr, ThisModule};
 
 pub use super::init::{InPlaceInit, Init, PinInit};
+
+pub use super::current;
rust/kernel/task.rs +92 -1

114 lines not on this page · raw message

Signature · 1 line
2.34.1
#23 lore raw

Re: [PATCH v2 10/13] rust: introduce `current`

Quoted 110 lines · Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This allows Rust code to get a reference to the current task without having to increment the refcount, but still guaranteeing memory safety.

---
v1 -> v2: Make current a macro to prevent it from escaping the caller

  rust/helpers.c         |  6 +++
  rust/kernel/prelude.rs |  2 +
  rust/kernel/task.rs    | 93 +++++++++++++++++++++++++++++++++++++++++-
  3 files changed, 100 insertions(+), 1 deletion(-)
rust/helpers.c +6 -0
index 58a194042c86..96441744030e 100644
@@ -100,6 +100,12 @@ bool rust_helper_refcount_dec_and_test(refcount_t *r)
  }
  EXPORT_SYMBOL_GPL(rust_helper_refcount_dec_and_test);
 
+struct task_struct *rust_helper_get_current(void)
+{
+	return current;
+}
+EXPORT_SYMBOL_GPL(rust_helper_get_current);
+
  void rust_helper_get_task_struct(struct task_struct *t)
  {
  	get_task_struct(t);
rust/kernel/prelude.rs +2 -0
index fcdc511d2ce8..c28587d68ebc 100644
@@ -36,3 +36,5 @@ pub use super::error::{code::*, Error, Result};
  pub use super::{str::CStr, ThisModule};
 
  pub use super::init::{InPlaceInit, Init, PinInit};
+
+pub use super::current;
rust/kernel/task.rs +47 -1
index 8d7a8222990f..468387a5f7eb 100644
@@ -5,7 +5,17 @@
  //! C header: [`include/linux/sched.h`](../../../../include/linux/sched.h).
 
  use crate::bindings;
-use core::{cell::UnsafeCell, ptr};
+use core::{cell::UnsafeCell, marker::PhantomData, ops::Deref, ptr};
+
+/// Returns the currently running task.
+#[macro_export]
+macro_rules! current {
+    () => {
+        // SAFETY: Deref + addr-of below create a temporary `TaskRef` that cannot outlive the
+        // caller.
+        unsafe { &*$crate::task::Task::current() }
+    };
+}
 
  /// Wraps the kernel's `struct task_struct`.
  ///
@@ -13,6 +23,42 @@ use core::{cell::UnsafeCell, ptr};
  ///
  /// Instances of this type are always ref-counted, that is, a call to `get_task_struct` ensures
  /// that the allocation remains valid at least until the matching call to `put_task_struct`.
+///
+/// # Examples
+///
+/// The following is an example of getting the PID of the current thread with zero additional cost
+/// when compared to the C version:
+///
+/// ```
+/// let pid = current!().pid();
+/// ```
+///
+/// Getting the PID of the current process, also zero additional cost:
+///
+/// ```
+/// let pid = current!().group_leader().pid();
+/// ```
+///
+/// Getting the current task and storing it in some struct. The reference count is automatically
+/// incremented when creating `State` and decremented when it is dropped:
+///
+/// ```
+/// use kernel::{task::Task, types::ARef};
+///
+/// struct State {
+///     creator: ARef<Task>,
+///     index: u32,
+/// }
+///
+/// impl State {
+///     fn new() -> Self {
+///         Self {
+///             creator: current!().into(),
+///             index: 0,
+///         }
+///     }
+/// }
+/// ```
  #[repr(transparent)]
  pub struct Task(pub(crate) UnsafeCell<bindings::task_struct>);
 

rust/kernel/task.rs unsafe impl Sync for Task {} · line 75

Quoted 5 lines
rust/kernel/task.rs +2 -0
@@ -25,6 +71,24 @@ unsafe impl Sync for Task {}
  type Pid = bindings::pid_t;
 
  impl Task {
+    /// Returns a task reference for the currently executing task/thread.
+    ///

Add a link to the current! macro as a safe version of this function.

Quoted 40 lines
rust/kernel/task.rs +33 -0
+    /// # Safety
+    ///
+    /// Callers must ensure that the returned [`TaskRef`] doesn't outlive the current task/thread.
+    pub unsafe fn current<'a>() -> TaskRef<'a> {
+        // SAFETY: Just an FFI call with no additional safety requirements.
+        let ptr = unsafe { bindings::get_current() };
+
+        TaskRef {
+            // SAFETY: If the current thread is still running, the current task is valid. Given
+            // that `TaskRef` is not `Send`, we know it cannot be transferred to another thread
+            // (where it could potentially outlive the caller).
+            task: unsafe { &*ptr.cast() },
+            _not_send: PhantomData,
+        }
+    }
+
      /// Returns the group leader of the given task.
      pub fn group_leader(&self) -> &Task {
          // SAFETY: By the type invariant, we know that `self.0` is valid.
@@ -69,3 +133,30 @@ unsafe impl crate::types::AlwaysRefCounted for Task {
          unsafe { bindings::put_task_struct(obj.cast().as_ptr()) }
      }
  }
+
+/// A wrapper for a shared reference to [`Task`] that isn't [`Send`].
+///
+/// We make this explicitly not [`Send`] so that we can use it to represent the current thread
+/// without having to increment/decrement the task's reference count.
+///
+/// # Invariants
+///
+/// The wrapped [`Task`] remains valid for the lifetime of the object.
+pub struct TaskRef<'a> {
+    task: &'a Task,
+    _not_send: PhantomData<*mut ()>,
+}
+
+impl Deref for TaskRef<'_> {
+    type Target = Task;
+

rust/kernel/task.rs unsafe impl crate::types::AlwaysRefCounted for Task { · line 162

Quoted 10 lines
rust/kernel/task.rs +10 -0
+    fn deref(&self) -> &Self::Target {
+        self.task
+    }
+}
+
+impl From<TaskRef<'_>> for crate::types::ARef<Task> {
+    fn from(t: TaskRef<'_>) -> Self {
+        t.deref().into()
+    }
+}

Maybe we can hide this struct and return an impl Deref<Target = Task> in Task::current instead (it will still be !Send)? Users do not really need to see this implementation detail.

--
Cheers,
Benno

Quoted 3 lines

--
2.34.1

#24 lore raw

Re: [PATCH v2 10/13] rust: introduce `current`

Quoted 111 lines · Benno Lossin
Quoted 109 lines · Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This allows Rust code to get a reference to the current task without having to increment the refcount, but still guaranteeing memory safety.

---
v1 -> v2: Make current a macro to prevent it from escaping the caller

  rust/helpers.c         |  6 +++
  rust/kernel/prelude.rs |  2 +
  rust/kernel/task.rs    | 93 +++++++++++++++++++++++++++++++++++++++++-
  3 files changed, 100 insertions(+), 1 deletion(-)
rust/helpers.c +6 -0
index 58a194042c86..96441744030e 100644
@@ -100,6 +100,12 @@ bool rust_helper_refcount_dec_and_test(refcount_t *r)
  }
  EXPORT_SYMBOL_GPL(rust_helper_refcount_dec_and_test);
 
+struct task_struct *rust_helper_get_current(void)
+{
+     return current;
+}
+EXPORT_SYMBOL_GPL(rust_helper_get_current);
+
  void rust_helper_get_task_struct(struct task_struct *t)
  {
      get_task_struct(t);
rust/kernel/prelude.rs +2 -0
index fcdc511d2ce8..c28587d68ebc 100644
@@ -36,3 +36,5 @@ pub use super::error::{code::*, Error, Result};
  pub use super::{str::CStr, ThisModule};
 
  pub use super::init::{InPlaceInit, Init, PinInit};
+
+pub use super::current;
rust/kernel/task.rs +47 -1
index 8d7a8222990f..468387a5f7eb 100644
@@ -5,7 +5,17 @@
  //! C header: [`include/linux/sched.h`](../../../../include/linux/sched.h).
 
  use crate::bindings;
-use core::{cell::UnsafeCell, ptr};
+use core::{cell::UnsafeCell, marker::PhantomData, ops::Deref, ptr};
+
+/// Returns the currently running task.
+#[macro_export]
+macro_rules! current {
+    () => {
+        // SAFETY: Deref + addr-of below create a temporary `TaskRef` that cannot outlive the
+        // caller.
+        unsafe { &*$crate::task::Task::current() }
+    };
+}
 
  /// Wraps the kernel's `struct task_struct`.
  ///
@@ -13,6 +23,42 @@ use core::{cell::UnsafeCell, ptr};
  ///
  /// Instances of this type are always ref-counted, that is, a call to `get_task_struct` ensures
  /// that the allocation remains valid at least until the matching call to `put_task_struct`.
+///
+/// # Examples
+///
+/// The following is an example of getting the PID of the current thread with zero additional cost
+/// when compared to the C version:
+///
+/// ```
+/// let pid = current!().pid();
+/// ```
+///
+/// Getting the PID of the current process, also zero additional cost:
+///
+/// ```
+/// let pid = current!().group_leader().pid();
+/// ```
+///
+/// Getting the current task and storing it in some struct. The reference count is automatically
+/// incremented when creating `State` and decremented when it is dropped:
+///
+/// ```
+/// use kernel::{task::Task, types::ARef};
+///
+/// struct State {
+///     creator: ARef<Task>,
+///     index: u32,
+/// }
+///
+/// impl State {
+///     fn new() -> Self {
+///         Self {
+///             creator: current!().into(),
+///             index: 0,
+///         }
+///     }
+/// }
+/// ```
  #[repr(transparent)]
  pub struct Task(pub(crate) UnsafeCell<bindings::task_struct>);
 
Quoted 8 lines

rust/kernel/task.rs unsafe impl Sync for Task {} · line 75

Quoted 6 lines
rust/kernel/task.rs +2 -0
@@ -25,6 +71,24 @@ unsafe impl Sync for Task {}
  type Pid = bindings::pid_t;
 
  impl Task {
+    /// Returns a task reference for the currently executing task/thread.
+    ///

Add a link to the current! macro as a safe version of this function.

Good idea, I'll add it in v3.

Quoted 46 lines
Quoted 46 lines
rust/kernel/task.rs +39 -0
+    /// # Safety
+    ///
+    /// Callers must ensure that the returned [`TaskRef`] doesn't outlive the current task/thread.
+    pub unsafe fn current<'a>() -> TaskRef<'a> {
+        // SAFETY: Just an FFI call with no additional safety requirements.
+        let ptr = unsafe { bindings::get_current() };
+
+        TaskRef {
+            // SAFETY: If the current thread is still running, the current task is valid. Given
+            // that `TaskRef` is not `Send`, we know it cannot be transferred to another thread
+            // (where it could potentially outlive the caller).
+            task: unsafe { &*ptr.cast() },
+            _not_send: PhantomData,
+        }
+    }
+
      /// Returns the group leader of the given task.
      pub fn group_leader(&self) -> &Task {
          // SAFETY: By the type invariant, we know that `self.0` is valid.
@@ -69,3 +133,30 @@ unsafe impl crate::types::AlwaysRefCounted for Task {
          unsafe { bindings::put_task_struct(obj.cast().as_ptr()) }
      }
  }
+
+/// A wrapper for a shared reference to [`Task`] that isn't [`Send`].
+///
+/// We make this explicitly not [`Send`] so that we can use it to represent the current thread
+/// without having to increment/decrement the task's reference count.
+///
+/// # Invariants
+///
+/// The wrapped [`Task`] remains valid for the lifetime of the object.
+pub struct TaskRef<'a> {
+    task: &'a Task,
+    _not_send: PhantomData<*mut ()>,
+}
+
+impl Deref for TaskRef<'_> {
+    type Target = Task;
+
+    fn deref(&self) -> &Self::Target {
+        self.task
+    }
+}
+
+impl From<TaskRef<'_>> for crate::types::ARef<Task> {
Quoted 8 lines

rust/kernel/task.rs unsafe impl crate::types::AlwaysRefCounted for Task { · line 162

Quoted 4 lines
rust/kernel/task.rs +4 -0
+    fn from(t: TaskRef<'_>) -> Self {
+        t.deref().into()
+    }
+}

Maybe we can hide this struct and return an impl Deref<Target = Task> in Task::current instead (it will still be !Send)? Users do not really need to see this implementation detail.

Hmm, I was a bit concerned with the impl of From<TaskRef> for ARef<Task>, but it seems to work. I moved the whole type into Task::current for v3.

Thanks for review!

Cheers,
-Wedson

#25 lore raw

PATCH v2 11/13 rust: lock: add `Guard::do_unlocked`

In reply to Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

It releases the lock, executes some function provided by the caller, then reacquires the lock. This is preparation for the implementation of condvars, which will sleep after between unlocking and relocking.

We need an explicit relock method for primitives like SpinLock that have an irqsave variant: we use the guard state to determine if the lock was originally acquired with the regular lock function or lock_irqsave.

---
v1 -> v2: No changes

 rust/kernel/sync/lock.rs          | 25 +++++++++++++++++++++++++
 rust/kernel/sync/lock/spinlock.rs | 17 +++++++++++++++--
 2 files changed, 40 insertions(+), 2 deletions(-)
rust/kernel/sync/lock.rs +25 -0
index 491446c3a074..ae20277c39c8 100644
@@ -22,6 +22,9 @@ pub mod spinlock;
 ///
 /// - Implementers must ensure that only one thread/CPU may access the protected data once the lock
 /// is owned, that is, between calls to `lock` and `unlock`.
+/// - Implementers must also ensure that `relock` uses the same locking method as the original
+/// lock operation. For example, it should disable interrupts if [`IrqSaveBackend::lock_irqsave`]
+/// is used.
 pub unsafe trait Backend {
     /// The state required by the lock.
     type State;
@@ -55,6 +58,17 @@ pub unsafe trait Backend {
     ///
     /// It must only be called by the current owner of the lock.
     unsafe fn unlock(ptr: *mut Self::State, guard_state: &Self::GuardState);
+
+    /// Reacquires the lock, making the caller its owner.
+    ///
+    /// # Safety
+    ///
+    /// Callers must ensure that `state` comes from a previous call to [`Backend::lock`] (or
+    /// variant) that has been unlocked with [`Backend::unlock`] and will be relocked now.
+    unsafe fn relock(ptr: *mut Self::State, guard_state: &mut Self::GuardState) {
+        // SAFETY: The safety requirements ensure that the lock is initialised.
+        *guard_state = unsafe { Self::lock(ptr) };
+    }
 }
 
 /// The "backend" of a lock that supports the irq-save variant.
@@ -162,6 +176,17 @@ pub struct Guard<'a, T: ?Sized, B: Backend> {
 // SAFETY: `Guard` is sync when the data protected by the lock is also sync.
 unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {}
 
+impl<T: ?Sized, B: Backend> Guard<'_, T, B> {
+    #[allow(dead_code)]
+    pub(crate) fn do_unlocked(&mut self, cb: impl FnOnce()) {
+        // SAFETY: The caller owns the lock, so it is safe to unlock it.
+        unsafe { B::unlock(self.lock.state.get(), &self.state) };
+        cb();
+        // SAFETY: The lock was just unlocked above and is being relocked now.
+        unsafe { B::relock(self.lock.state.get(), &mut self.state) };
+    }
+}
+
 impl<T: ?Sized, B: Backend> core::ops::Deref for Guard<'_, T, B> {
     type Target = T;
 
rust/kernel/sync/lock/spinlock.rs +15 -2
index 34dec09a97c0..e2a2f68e6d93 100644
@@ -4,6 +4,7 @@
 //!
 //! This module allows Rust code to use the kernel's `spinlock_t`.
 
+use super::IrqSaveBackend;
 use crate::bindings;
 
 /// Creates a [`SpinLock`] initialiser with the given name and a newly-created lock class.
@@ -95,7 +96,8 @@ pub type SpinLock<T> = super::Lock<T, SpinLockBackend>;
 /// A kernel `spinlock_t` lock backend.
 pub struct SpinLockBackend;
 
-// SAFETY: The underlying kernel `spinlock_t` object ensures mutual exclusion.
+// SAFETY: The underlying kernel `spinlock_t` object ensures mutual exclusion. `relock` uses the
+// same scheme as `unlock` to figure out which locking method was used originally.
 unsafe impl super::Backend for SpinLockBackend {
     type State = bindings::spinlock_t;
     type GuardState = Option<core::ffi::c_ulong>;
@@ -127,13 +129,24 @@ unsafe impl super::Backend for SpinLockBackend {
             None => unsafe { bindings::spin_unlock(ptr) },
         }
     }
+
+    unsafe fn relock(ptr: *mut Self::State, guard_state: &mut Self::GuardState) {
+        let _ = match guard_state {
+            // SAFETY: The safety requiments of this function ensure that `ptr` has been
+            // initialised.
+            None => unsafe { Self::lock(ptr) },
+            // SAFETY: The safety requiments of this function ensure that `ptr` has been
+            // initialised.
+            Some(_) => unsafe { Self::lock_irqsave(ptr) },
+        };
+    }
 }
 
 // SAFETY: The underlying kernel `spinlock_t` object ensures mutual exclusion. We use the `irqsave`
 // variant of the C lock acquisition functions to disable interrupts and retrieve the original
 // interrupt state, and the `irqrestore` variant of the lock release functions to restore the state
 // in `unlock` -- we use the guard context to determine which method was used to acquire the lock.
-unsafe impl super::IrqSaveBackend for SpinLockBackend {
+unsafe impl IrqSaveBackend for SpinLockBackend {
     unsafe fn lock_irqsave(ptr: *mut Self::State) -> Self::GuardState {
         // SAFETY: The safety requirements of this function ensure that `ptr` points to valid
         // memory, and that it has been initialised before.
Signature · 1 line
2.34.1
#26 lore raw

PATCH v2 12/13 rust: sync: introduce `CondVar`

In reply to Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This is the traditional condition variable or monitor synchronisation primitive. It is implemented with C's wait_queue_head_t.

It allows users to release a lock and go to sleep while guaranteeing that notifications won't be missed. This is achieved by enqueuing a wait entry before releasing the lock.

Cc Peter Zijlstra <[email protected]>
Cc Ingo Molnar <[email protected]>
Cc Will Deacon <[email protected]>
Cc Waiman Long <[email protected]>

---
v1 -> v2: Use the new current macro

 rust/bindings/bindings_helper.h |   1 +
 rust/helpers.c                  |   7 ++
 rust/kernel/sync.rs             |   2 +
 rust/kernel/sync/condvar.rs     | 178 ++++++++++++++++++++++++++++++++
 rust/kernel/sync/lock.rs        |   1 -
 5 files changed, 188 insertions(+), 1 deletion(-)
 create mode 100644 rust/kernel/sync/condvar.rs
rust/bindings/bindings_helper.h +1 -0
index 03656a44a83f..50e7a76d5455 100644
@@ -8,6 +8,7 @@
 
 #include <linux/slab.h>
 #include <linux/refcount.h>
+#include <linux/wait.h>
 #include <linux/sched.h>
 
 /* `bindgen` gets confused at certain things. */
rust/helpers.c +7 -0
index 96441744030e..8ff2559c1572 100644
@@ -24,6 +24,7 @@
 #include <linux/mutex.h>
 #include <linux/spinlock.h>
 #include <linux/sched/signal.h>
+#include <linux/wait.h>
 
 __noreturn void rust_helper_BUG(void)
 {
@@ -76,6 +77,12 @@ void rust_helper_spin_unlock_irqrestore(spinlock_t *lock, unsigned long flags)
 }
 EXPORT_SYMBOL_GPL(rust_helper_spin_unlock_irqrestore);
 
+void rust_helper_init_wait(struct wait_queue_entry *wq_entry)
+{
+	init_wait(wq_entry);
+}
+EXPORT_SYMBOL_GPL(rust_helper_init_wait);
+
 int rust_helper_signal_pending(struct task_struct *t)
 {
 	return signal_pending(t);
rust/kernel/sync.rs +2 -0
index ed07437d7d55..d6dd0e2c1678 100644
@@ -8,9 +8,11 @@
 use crate::types::Opaque;
 
 mod arc;
+mod condvar;
 pub mod lock;
 
 pub use arc::{Arc, ArcBorrow, UniqueArc};
+pub use condvar::CondVar;
 pub use lock::{mutex::Mutex, spinlock::SpinLock};
 
 /// Represents a lockdep class. It's a wrapper around C's `lock_class_key`.
rust/kernel/sync/condvar.rs new file +178 -0

178 lines not on this page · raw message

rust/kernel/sync/lock.rs +0 -1
index ae20277c39c8..f52ba9ab1b70 100644
@@ -177,7 +177,6 @@ pub struct Guard<'a, T: ?Sized, B: Backend> {
 unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {}
 
 impl<T: ?Sized, B: Backend> Guard<'_, T, B> {
-    #[allow(dead_code)]
     pub(crate) fn do_unlocked(&mut self, cb: impl FnOnce()) {
         // SAFETY: The caller owns the lock, so it is safe to unlock it.
         unsafe { B::unlock(self.lock.state.get(), &self.state) };
Signature · 1 line
2.34.1
#27 lore raw

PATCH v2 13/13 rust: sync: introduce `LockedBy`

In reply to Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This allows us to have data protected by a lock despite not being wrapped by it. Access is granted by providing evidence that the lock is held by the caller.

---
v1 -> v2: Added build_assert to rule out zero-sized types

 rust/kernel/sync.rs           |   2 +
 rust/kernel/sync/lock.rs      |   2 +-
 rust/kernel/sync/locked_by.rs | 128 ++++++++++++++++++++++++++++++++++
 3 files changed, 131 insertions(+), 1 deletion(-)
 create mode 100644 rust/kernel/sync/locked_by.rs
rust/kernel/sync.rs +2 -0
index d6dd0e2c1678..f8edb6d0d794 100644
@@ -10,10 +10,12 @@ use crate::types::Opaque;
 mod arc;
 mod condvar;
 pub mod lock;
+mod locked_by;
 
 pub use arc::{Arc, ArcBorrow, UniqueArc};
 pub use condvar::CondVar;
 pub use lock::{mutex::Mutex, spinlock::SpinLock};
+pub use locked_by::LockedBy;
 
 /// Represents a lockdep class. It's a wrapper around C's `lock_class_key`.
 #[repr(transparent)]
rust/kernel/sync/lock.rs +1 -1
index f52ba9ab1b70..51c996ca2109 100644
@@ -111,7 +111,7 @@ pub struct Lock<T: ?Sized, B: Backend> {
     _pin: PhantomPinned,
 
     /// The data protected by the lock.
-    data: UnsafeCell<T>,
+    pub(crate) data: UnsafeCell<T>,
 }
 
 // SAFETY: `Lock` can be transferred across thread boundaries iff the data it protects can.
rust/kernel/sync/locked_by.rs new file +128 -0

128 lines not on this page · raw message

Signature · 1 line
2.34.1
#28 lore raw

Re: [PATCH v2 13/13] rust: sync: introduce `LockedBy`

Quoted 59 lines · Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This allows us to have data protected by a lock despite not being wrapped by it. Access is granted by providing evidence that the lock is held by the caller.

---
v1 -> v2: Added build_assert to rule out zero-sized types

  rust/kernel/sync.rs           |   2 +
  rust/kernel/sync/lock.rs      |   2 +-
  rust/kernel/sync/locked_by.rs | 128 ++++++++++++++++++++++++++++++++++
  3 files changed, 131 insertions(+), 1 deletion(-)

create mode 100644 rust/kernel/sync/locked_by.rs

rust/kernel/sync.rs +2 -0
index d6dd0e2c1678..f8edb6d0d794 100644
@@ -10,10 +10,12 @@ use crate::types::Opaque;
  mod arc;
  mod condvar;
  pub mod lock;
+mod locked_by;
 
  pub use arc::{Arc, ArcBorrow, UniqueArc};
  pub use condvar::CondVar;
  pub use lock::{mutex::Mutex, spinlock::SpinLock};
+pub use locked_by::LockedBy;
 
  /// Represents a lockdep class. It's a wrapper around C's `lock_class_key`.
  #[repr(transparent)]
rust/kernel/sync/lock.rs +1 -1
index f52ba9ab1b70..51c996ca2109 100644
@@ -111,7 +111,7 @@ pub struct Lock<T: ?Sized, B: Backend> {
      _pin: PhantomPinned,
 
      /// The data protected by the lock.
-    data: UnsafeCell<T>,
+    pub(crate) data: UnsafeCell<T>,
  }
 
  // SAFETY: `Lock` can be transferred across thread boundaries iff the data it protects can.
rust/kernel/sync/locked_by.rs new file +7 -0
new file mode 100644
index 000000000000..191e37d804e5
@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! A wrapper for data protected by a lock that does not wrap it.
+
+use super::{lock::Backend, lock::Lock};
+use core::{cell::UnsafeCell, ptr};
+

rust/kernel/sync/locked_by.rs line 17

Quoted 10 lines
rust/kernel/sync/locked_by.rs new file +10 -0
+/// Allows access to some data to be serialised by a lock that does not wrap it.
+///
+/// In most cases, data protected by a lock is wrapped by the appropriate lock type, e.g.,
+/// [`super::Mutex`] or [`super::SpinLock`]. [`LockedBy`] is meant for cases when this is not
+/// possible. For example, if a container has a lock and some data in the contained elements needs
+/// to be protected by the same lock.
+///
+/// [`LockedBy`] wraps the data in lieu of another locking primitive, and only allows access to it
+/// when the caller shows evidence that the 'external' lock is locked.
+///

Maybe add that the access/access_mut functions panic when the supplied external value is not the correct one.

Quoted 66 lines
rust/kernel/sync/locked_by.rs new file +66 -0
+/// # Examples
+///
+/// The following is an example for illustrative purposes: `InnerDirectory::bytes_used` is an
+/// aggregate of all `InnerFile::bytes_used` and must be kept consistent; so we wrap `InnerFile` in
+/// a `LockedBy` so that it shares a lock with `InnerDirectory`. This allows us to enforce at
+/// compile-time that access to `InnerFile` is only granted when an `InnerDirectory` is also
+/// locked; we enforce at run time that the right `InnerDirectory` is locked.
+///
+/// ```
+/// use kernel::sync::{LockedBy, Mutex};
+///
+/// struct InnerFile {
+///     bytes_used: u64,
+/// }
+///
+/// struct File {
+///     _ino: u32,
+///     inner: LockedBy<InnerFile, InnerDirectory>,
+/// }
+///
+/// struct InnerDirectory {
+///     /// The sum of the bytes used by all files.
+///     bytes_used: u64,
+///     _files: Vec<File>,
+/// }
+///
+/// struct Directory {
+///     _ino: u32,
+///     inner: Mutex<InnerDirectory>,
+/// }
+///
+/// /// Prints `bytes_used` from both the directory and file.
+/// fn print_bytes_used(dir: &Directory, file: &File) {
+///     let guard = dir.inner.lock();
+///     let inner_file = file.inner.access(&guard);
+///     pr_info!("{} {}", guard.bytes_used, inner_file.bytes_used);
+/// }
+///
+/// /// Increments `bytes_used` for both the directory and file.
+/// fn inc_bytes_used(dir: &Directory, file: &File) {
+///     let mut guard = dir.inner.lock();
+///     guard.bytes_used += 10;
+///
+///     let file_inner = file.inner.access_mut(&mut guard);
+///     file_inner.bytes_used += 10;
+/// }
+///
+/// /// Creates a new file.
+/// fn new_file(ino: u32, dir: &Directory) -> File {
+///     File {
+///         _ino: ino,
+///         inner: LockedBy::new(&dir.inner, InnerFile { bytes_used: 0 }),
+///     }
+/// }
+/// ```
+pub struct LockedBy<T: ?Sized, U: ?Sized> {
+    owner: *const U,
+    data: UnsafeCell<T>,
+}
+
+// SAFETY: `LockedBy` can be transferred across thread boundaries iff the data it protects can.
+unsafe impl<T: ?Sized + Send, U: ?Sized> Send for LockedBy<T, U> {}
+
+// SAFETY: `LockedBy` serialises the interior mutability it provides, so it is `Sync` as long as the
+// data it protects is `Send`.
+unsafe impl<T: ?Sized + Send, U: ?Sized> Sync for LockedBy<T, U> {}

rust/kernel/sync/locked_by.rs line 93

Quoted 10 lines
rust/kernel/sync/locked_by.rs new file +10 -0
+
+impl<T, U: ?Sized> LockedBy<T, U> {
+    /// Constructs a new instance of [`LockedBy`].
+    ///
+    /// It stores a raw pointer to the owner that is never dereferenced. It is only used to ensure
+    /// that the right owner is being used to access the protected data. If the owner is freed, the
+    /// data becomes inaccessible; if another instance of the owner is allocated *on the same
+    /// memory location*, the data becomes accessible again: none of this affects memory safety
+    /// because in any case at most one thread (or CPU) can access the protected data at a time.
+    pub fn new(owner: &Lock<U, impl Backend>, data: T) -> Self {

I think it would be sensible to also do the ZST check here, then it will fail immediately on construction (but also keep the other location, as it does not add any runtime cost).

Also, I think you should mention in the documentation that ZSTs are not supported. And it would be good to have an explaining comment on the build_assert! why we disallow ZSTs here.

rust/kernel/sync/locked_by.rs line 103

Quoted 10 lines
rust/kernel/sync/locked_by.rs new file +10 -0
+        Self {
+            owner: owner.data.get(),
+            data: UnsafeCell::new(data),
+        }
+    }
+}
+
+impl<T: ?Sized, U> LockedBy<T, U> {
+    /// Returns a reference to the protected data when the caller provides evidence (via a
+    /// reference) that the owner is locked.

Maybe add a # Panic section, also for access_mut.

--
Cheers,
Benno

Quoted 28 lines
rust/kernel/sync/locked_by.rs new file +25 -1
+    pub fn access<'a>(&'a self, owner: &'a U) -> &'a T {
+        crate::build_assert!(core::mem::size_of::<U>() > 0);
+        if !ptr::eq(owner, self.owner) {
+            panic!("mismatched owners");
+        }
+
+        // SAFETY: `owner` is evidence that the owner is locked.
+        unsafe { &*self.data.get() }
+    }
+
+    /// Returns a mutable reference to the protected data when the caller provides evidence (via a
+    /// mutable owner) that the owner is locked mutably.
+    ///
+    /// Showing a mutable reference to the owner is sufficient because we know no other references
+    /// can exist to it.
+    pub fn access_mut<'a>(&'a self, owner: &'a mut U) -> &'a mut T {
+        crate::build_assert!(core::mem::size_of::<U>() > 0);
+        if !ptr::eq(owner, self.owner) {
+            panic!("mismatched owners");
+        }
+
+        // SAFETY: `owner` is evidence that there is only one reference to the owner.
+        unsafe { &mut *self.data.get() }
+    }
+}
--

2.34.1

#29 lore raw

Re: [PATCH v2 13/13] rust: sync: introduce `LockedBy`

Quoted 66 lines · Benno Lossin
Quoted 64 lines · Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This allows us to have data protected by a lock despite not being wrapped by it. Access is granted by providing evidence that the lock is held by the caller.

---
v1 -> v2: Added build_assert to rule out zero-sized types

  rust/kernel/sync.rs           |   2 +
  rust/kernel/sync/lock.rs      |   2 +-
  rust/kernel/sync/locked_by.rs | 128 ++++++++++++++++++++++++++++++++++
  3 files changed, 131 insertions(+), 1 deletion(-)

create mode 100644 rust/kernel/sync/locked_by.rs

rust/kernel/sync.rs +2 -0
index d6dd0e2c1678..f8edb6d0d794 100644
@@ -10,10 +10,12 @@ use crate::types::Opaque;
  mod arc;
  mod condvar;
  pub mod lock;
+mod locked_by;
 
  pub use arc::{Arc, ArcBorrow, UniqueArc};
  pub use condvar::CondVar;
  pub use lock::{mutex::Mutex, spinlock::SpinLock};
+pub use locked_by::LockedBy;
 
  /// Represents a lockdep class. It's a wrapper around C's `lock_class_key`.
  #[repr(transparent)]
rust/kernel/sync/lock.rs +1 -1
index f52ba9ab1b70..51c996ca2109 100644
@@ -111,7 +111,7 @@ pub struct Lock<T: ?Sized, B: Backend> {
      _pin: PhantomPinned,
 
      /// The data protected by the lock.
-    data: UnsafeCell<T>,
+    pub(crate) data: UnsafeCell<T>,
  }
 
  // SAFETY: `Lock` can be transferred across thread boundaries iff the data it protects can.
rust/kernel/sync/locked_by.rs new file +12 -0
new file mode 100644
index 000000000000..191e37d804e5
@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! A wrapper for data protected by a lock that does not wrap it.
+
+use super::{lock::Backend, lock::Lock};
+use core::{cell::UnsafeCell, ptr};
+
+/// Allows access to some data to be serialised by a lock that does not wrap it.
+///
+/// In most cases, data protected by a lock is wrapped by the appropriate lock type, e.g.,
+/// [`super::Mutex`] or [`super::SpinLock`]. [`LockedBy`] is meant for cases when this is not
+/// possible. For example, if a container has a lock and some data in the contained elements needs
Quoted 8 lines

rust/kernel/sync/locked_by.rs line 17

Quoted 5 lines
rust/kernel/sync/locked_by.rs new file +5 -0
+/// to be protected by the same lock.
+///
+/// [`LockedBy`] wraps the data in lieu of another locking primitive, and only allows access to it
+/// when the caller shows evidence that the 'external' lock is locked.
+///

Maybe add that the access/access_mut functions panic when the supplied external value is not the correct one.

Will do for v3.

Quoted 72 lines
Quoted 72 lines
rust/kernel/sync/locked_by.rs new file +72 -0
+/// # Examples
+///
+/// The following is an example for illustrative purposes: `InnerDirectory::bytes_used` is an
+/// aggregate of all `InnerFile::bytes_used` and must be kept consistent; so we wrap `InnerFile` in
+/// a `LockedBy` so that it shares a lock with `InnerDirectory`. This allows us to enforce at
+/// compile-time that access to `InnerFile` is only granted when an `InnerDirectory` is also
+/// locked; we enforce at run time that the right `InnerDirectory` is locked.
+///
+/// ```
+/// use kernel::sync::{LockedBy, Mutex};
+///
+/// struct InnerFile {
+///     bytes_used: u64,
+/// }
+///
+/// struct File {
+///     _ino: u32,
+///     inner: LockedBy<InnerFile, InnerDirectory>,
+/// }
+///
+/// struct InnerDirectory {
+///     /// The sum of the bytes used by all files.
+///     bytes_used: u64,
+///     _files: Vec<File>,
+/// }
+///
+/// struct Directory {
+///     _ino: u32,
+///     inner: Mutex<InnerDirectory>,
+/// }
+///
+/// /// Prints `bytes_used` from both the directory and file.
+/// fn print_bytes_used(dir: &Directory, file: &File) {
+///     let guard = dir.inner.lock();
+///     let inner_file = file.inner.access(&guard);
+///     pr_info!("{} {}", guard.bytes_used, inner_file.bytes_used);
+/// }
+///
+/// /// Increments `bytes_used` for both the directory and file.
+/// fn inc_bytes_used(dir: &Directory, file: &File) {
+///     let mut guard = dir.inner.lock();
+///     guard.bytes_used += 10;
+///
+///     let file_inner = file.inner.access_mut(&mut guard);
+///     file_inner.bytes_used += 10;
+/// }
+///
+/// /// Creates a new file.
+/// fn new_file(ino: u32, dir: &Directory) -> File {
+///     File {
+///         _ino: ino,
+///         inner: LockedBy::new(&dir.inner, InnerFile { bytes_used: 0 }),
+///     }
+/// }
+/// ```
+pub struct LockedBy<T: ?Sized, U: ?Sized> {
+    owner: *const U,
+    data: UnsafeCell<T>,
+}
+
+// SAFETY: `LockedBy` can be transferred across thread boundaries iff the data it protects can.
+unsafe impl<T: ?Sized + Send, U: ?Sized> Send for LockedBy<T, U> {}
+
+// SAFETY: `LockedBy` serialises the interior mutability it provides, so it is `Sync` as long as the
+// data it protects is `Send`.
+unsafe impl<T: ?Sized + Send, U: ?Sized> Sync for LockedBy<T, U> {}
+
+impl<T, U: ?Sized> LockedBy<T, U> {
+    /// Constructs a new instance of [`LockedBy`].
+    ///
+    /// It stores a raw pointer to the owner that is never dereferenced. It is only used to ensure
+    /// that the right owner is being used to access the protected data. If the owner is freed, the
Quoted 8 lines

rust/kernel/sync/locked_by.rs line 93

Quoted 4 lines
rust/kernel/sync/locked_by.rs new file +4 -0
+    /// data becomes inaccessible; if another instance of the owner is allocated *on the same
+    /// memory location*, the data becomes accessible again: none of this affects memory safety
+    /// because in any case at most one thread (or CPU) can access the protected data at a time.
+    pub fn new(owner: &Lock<U, impl Backend>, data: T) -> Self {

I think it would be sensible to also do the ZST check here, then it will fail immediately on construction (but also keep the other location, as it does not add any runtime cost).

This ZST restriction on U applies to access and access_mut, but doesn't apply to versions of these functions that work on Guard instances, which we have in the rust branch but not here yet. (The restrictions there are different.) So it doesn't make sense to block the _creation_ of LockedBy instances if access/access_mut are never used.

Quoted 3 lines

Also, I think you should mention in the documentation that ZSTs are not supported. And it would be good to have an explaining comment on the build_assert! why we disallow ZSTs here.

I'll add comments in v3 to access/access_mut.

Quoted 46 lines

rust/kernel/sync/locked_by.rs line 103

Quoted 10 lines
rust/kernel/sync/locked_by.rs new file +10 -0
+        Self {
+            owner: owner.data.get(),
+            data: UnsafeCell::new(data),
+        }
+    }
+}
+
+impl<T: ?Sized, U> LockedBy<T, U> {
+    /// Returns a reference to the protected data when the caller provides evidence (via a
+    /// reference) that the owner is locked.

Maybe add a # Panic section, also for access_mut.

--
Cheers,
Benno

Quoted 28 lines
rust/kernel/sync/locked_by.rs new file +25 -1
+    pub fn access<'a>(&'a self, owner: &'a U) -> &'a T {
+        crate::build_assert!(core::mem::size_of::<U>() > 0);
+        if !ptr::eq(owner, self.owner) {
+            panic!("mismatched owners");
+        }
+
+        // SAFETY: `owner` is evidence that the owner is locked.
+        unsafe { &*self.data.get() }
+    }
+
+    /// Returns a mutable reference to the protected data when the caller provides evidence (via a
+    /// mutable owner) that the owner is locked mutably.
+    ///
+    /// Showing a mutable reference to the owner is sufficient because we know no other references
+    /// can exist to it.
+    pub fn access_mut<'a>(&'a self, owner: &'a mut U) -> &'a mut T {
+        crate::build_assert!(core::mem::size_of::<U>() > 0);
+        if !ptr::eq(owner, self.owner) {
+            panic!("mismatched owners");
+        }
+
+        // SAFETY: `owner` is evidence that there is only one reference to the owner.
+        unsafe { &mut *self.data.get() }
+    }
+}
--

2.34.1

#30 lore raw

Re: [PATCH v2 13/13] rust: sync: introduce `LockedBy`

Quoted 159 lines · Wedson Almeida Filho
Quoted 66 lines · Benno Lossin
Quoted 64 lines · Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

This allows us to have data protected by a lock despite not being wrapped by it. Access is granted by providing evidence that the lock is held by the caller.

---
v1 -> v2: Added build_assert to rule out zero-sized types

   rust/kernel/sync.rs           |   2 +
   rust/kernel/sync/lock.rs      |   2 +-
   rust/kernel/sync/locked_by.rs | 128 ++++++++++++++++++++++++++++++++++
   3 files changed, 131 insertions(+), 1 deletion(-)

create mode 100644 rust/kernel/sync/locked_by.rs

rust/kernel/sync.rs +2 -0
index d6dd0e2c1678..f8edb6d0d794 100644
@@ -10,10 +10,12 @@ use crate::types::Opaque;
   mod arc;
   mod condvar;
   pub mod lock;
+mod locked_by;
 
   pub use arc::{Arc, ArcBorrow, UniqueArc};
   pub use condvar::CondVar;
   pub use lock::{mutex::Mutex, spinlock::SpinLock};
+pub use locked_by::LockedBy;
 
   /// Represents a lockdep class. It's a wrapper around C's `lock_class_key`.
   #[repr(transparent)]
rust/kernel/sync/lock.rs +1 -1
index f52ba9ab1b70..51c996ca2109 100644
@@ -111,7 +111,7 @@ pub struct Lock<T: ?Sized, B: Backend> {
       _pin: PhantomPinned,
 
       /// The data protected by the lock.
-    data: UnsafeCell<T>,
+    pub(crate) data: UnsafeCell<T>,
   }
 
   // SAFETY: `Lock` can be transferred across thread boundaries iff the data it protects can.
rust/kernel/sync/locked_by.rs new file +12 -0
new file mode 100644
index 000000000000..191e37d804e5
@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! A wrapper for data protected by a lock that does not wrap it.
+
+use super::{lock::Backend, lock::Lock};
+use core::{cell::UnsafeCell, ptr};
+
+/// Allows access to some data to be serialised by a lock that does not wrap it.
+///
+/// In most cases, data protected by a lock is wrapped by the appropriate lock type, e.g.,
+/// [`super::Mutex`] or [`super::SpinLock`]. [`LockedBy`] is meant for cases when this is not
+/// possible. For example, if a container has a lock and some data in the contained elements needs
Quoted 8 lines

rust/kernel/sync/locked_by.rs line 17

Quoted 5 lines
rust/kernel/sync/locked_by.rs new file +5 -0
+/// to be protected by the same lock.
+///
+/// [`LockedBy`] wraps the data in lieu of another locking primitive, and only allows access to it
+/// when the caller shows evidence that the 'external' lock is locked.
+///

Maybe add that the access/access_mut functions panic when the supplied external value is not the correct one.

Will do for v3.

Quoted 72 lines
Quoted 72 lines
rust/kernel/sync/locked_by.rs new file +72 -0
+/// # Examples
+///
+/// The following is an example for illustrative purposes: `InnerDirectory::bytes_used` is an
+/// aggregate of all `InnerFile::bytes_used` and must be kept consistent; so we wrap `InnerFile` in
+/// a `LockedBy` so that it shares a lock with `InnerDirectory`. This allows us to enforce at
+/// compile-time that access to `InnerFile` is only granted when an `InnerDirectory` is also
+/// locked; we enforce at run time that the right `InnerDirectory` is locked.
+///
+/// ```
+/// use kernel::sync::{LockedBy, Mutex};
+///
+/// struct InnerFile {
+///     bytes_used: u64,
+/// }
+///
+/// struct File {
+///     _ino: u32,
+///     inner: LockedBy<InnerFile, InnerDirectory>,
+/// }
+///
+/// struct InnerDirectory {
+///     /// The sum of the bytes used by all files.
+///     bytes_used: u64,
+///     _files: Vec<File>,
+/// }
+///
+/// struct Directory {
+///     _ino: u32,
+///     inner: Mutex<InnerDirectory>,
+/// }
+///
+/// /// Prints `bytes_used` from both the directory and file.
+/// fn print_bytes_used(dir: &Directory, file: &File) {
+///     let guard = dir.inner.lock();
+///     let inner_file = file.inner.access(&guard);
+///     pr_info!("{} {}", guard.bytes_used, inner_file.bytes_used);
+/// }
+///
+/// /// Increments `bytes_used` for both the directory and file.
+/// fn inc_bytes_used(dir: &Directory, file: &File) {
+///     let mut guard = dir.inner.lock();
+///     guard.bytes_used += 10;
+///
+///     let file_inner = file.inner.access_mut(&mut guard);
+///     file_inner.bytes_used += 10;
+/// }
+///
+/// /// Creates a new file.
+/// fn new_file(ino: u32, dir: &Directory) -> File {
+///     File {
+///         _ino: ino,
+///         inner: LockedBy::new(&dir.inner, InnerFile { bytes_used: 0 }),
+///     }
+/// }
+/// ```
+pub struct LockedBy<T: ?Sized, U: ?Sized> {
+    owner: *const U,
+    data: UnsafeCell<T>,
+}
+
+// SAFETY: `LockedBy` can be transferred across thread boundaries iff the data it protects can.
+unsafe impl<T: ?Sized + Send, U: ?Sized> Send for LockedBy<T, U> {}
+
+// SAFETY: `LockedBy` serialises the interior mutability it provides, so it is `Sync` as long as the
+// data it protects is `Send`.
+unsafe impl<T: ?Sized + Send, U: ?Sized> Sync for LockedBy<T, U> {}
+
+impl<T, U: ?Sized> LockedBy<T, U> {
+    /// Constructs a new instance of [`LockedBy`].
+    ///
+    /// It stores a raw pointer to the owner that is never dereferenced. It is only used to ensure
+    /// that the right owner is being used to access the protected data. If the owner is freed, the
Quoted 8 lines

rust/kernel/sync/locked_by.rs line 93

Quoted 4 lines
rust/kernel/sync/locked_by.rs new file +4 -0
+    /// data becomes inaccessible; if another instance of the owner is allocated *on the same
+    /// memory location*, the data becomes accessible again: none of this affects memory safety
+    /// because in any case at most one thread (or CPU) can access the protected data at a time.
+    pub fn new(owner: &Lock<U, impl Backend>, data: T) -> Self {

I think it would be sensible to also do the ZST check here, then it will fail immediately on construction (but also keep the other location, as it does not add any runtime cost).

Quoted 6 lines

This ZST restriction on U applies to access and access_mut, but doesn't apply to versions of these functions that work on Guard instances, which we have in the rust branch but not here yet. (The restrictions there are different.) So it doesn't make sense to block the _creation_ of LockedBy instances if access/access_mut are never used.

Ah because you can only get a Guard safely via a Lock and at the moment, all locks cannot be zero-sized even if the data is.

But if we at some point decide to add a Backend with the State being a ZST, then this code becomes unsound.

What about adding a build_assert!(mem::size_of::<Lock<T, B>>() > 0) (you will sadly have to spell out the generic parameter of Backend). I worry that we might not remember all of these details when we add new locks.

--
Cheers,
Benno

Quoted 52 lines
Quoted 3 lines

Also, I think you should mention in the documentation that ZSTs are not supported. And it would be good to have an explaining comment on the build_assert! why we disallow ZSTs here.

I'll add comments in v3 to access/access_mut.

Quoted 46 lines

rust/kernel/sync/locked_by.rs line 103

Quoted 10 lines
rust/kernel/sync/locked_by.rs new file +10 -0
+        Self {
+            owner: owner.data.get(),
+            data: UnsafeCell::new(data),
+        }
+    }
+}
+
+impl<T: ?Sized, U> LockedBy<T, U> {
+    /// Returns a reference to the protected data when the caller provides evidence (via a
+    /// reference) that the owner is locked.

Maybe add a # Panic section, also for access_mut.

--
Cheers,
Benno

Quoted 28 lines
rust/kernel/sync/locked_by.rs new file +25 -1
+    pub fn access<'a>(&'a self, owner: &'a U) -> &'a T {
+        crate::build_assert!(core::mem::size_of::<U>() > 0);
+        if !ptr::eq(owner, self.owner) {
+            panic!("mismatched owners");
+        }
+
+        // SAFETY: `owner` is evidence that the owner is locked.
+        unsafe { &*self.data.get() }
+    }
+
+    /// Returns a mutable reference to the protected data when the caller provides evidence (via a
+    /// mutable owner) that the owner is locked mutably.
+    ///
+    /// Showing a mutable reference to the owner is sufficient because we know no other references
+    /// can exist to it.
+    pub fn access_mut<'a>(&'a self, owner: &'a mut U) -> &'a mut T {
+        crate::build_assert!(core::mem::size_of::<U>() > 0);
+        if !ptr::eq(owner, self.owner) {
+            panic!("mismatched owners");
+        }
+
+        // SAFETY: `owner` is evidence that there is only one reference to the owner.
+        unsafe { &mut *self.data.get() }
+    }
+}
--

2.34.1

#31 lore raw
In reply to Wedson Almeida Filho
Quoted 26 lines · Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

It is a wrapper around C's lock_class_key, which is used by the synchronisation primitives that are checked with lockdep. This is in preparation for introducing Rust abstractions for these primitives.

---
v1 -> v2: Fixed a typo in comment

 rust/kernel/sync.rs | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
rust/kernel/sync.rs +0 -0
index 33da23e3076d..84a4b560828c 100644
@@ -5,6 +5,51 @@
 //! This module contains the kernel APIs related to synchronisation that have been ported or
 //! wrapped for usage by Rust code in the kernel.

rust/kernel/sync.rs line 16

Quoted 10 lines
rust/kernel/sync.rs +6 -0
 
+use crate::types::Opaque;
+
 mod arc;
 
 pub use arc::{Arc, ArcBorrow, UniqueArc};
+
+/// Represents a lockdep class. It's a wrapper around C's `lock_class_key`.
+#[repr(transparent)]
+pub struct LockClassKey(Opaque<bindings::lock_class_key>);

Will this disappear into "nothing" if lockdep is disabled in the build?

If not, it should, if so, I couldn't see where that option was, sorry for the noise.

thanks,

greg k-h

#32 lore raw
Quoted 11 lines · Greg KH

rust/kernel/sync.rs line 16

Quoted 5 lines · Wedson Almeida Filho

From: Wedson Almeida Filho <[email protected]>

rust/kernel/sync.rs +3 -0
+/// Represents a lockdep class. It's a wrapper around C's `lock_class_key`.
+#[repr(transparent)]
+pub struct LockClassKey(Opaque<bindings::lock_class_key>);

Will this disappear into "nothing" if lockdep is disabled in the build?

If not, it should, if so, I couldn't see where that option was, sorry for the noise.

Yeah, the C definition of lock_class_key is an empty struct, which is a zero-sized type. So instances of this type will occupy 0 bytes.

We'll still have the cost of passing pointers from Rust to C of instances of this type, which we could add an alternate version (dependent on lockdep being enabled or not) in Rust to avoid, but since it will be optimised away when LTO is enabled and doesn't add up to much when LTO is disabled, we chose the simpler option of having a single implementation.

maintainer
#33 lore raw
In reply to Wedson Almeida Filho
Quoted 60 lines · On Wed, 5 Apr 2023 14:50:59 -0300 Wedson Almeida Filho <[email protected]>…

From: Wedson Almeida Filho <[email protected]>

It is a wrapper around C's lock_class_key, which is used by the synchronisation primitives that are checked with lockdep. This is in preparation for introducing Rust abstractions for these primitives.

---
v1 -> v2: Fixed a typo in comment

 rust/kernel/sync.rs | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
rust/kernel/sync.rs +30 -0
index 33da23e3076d..84a4b560828c 100644
@@ -5,6 +5,51 @@
 //! This module contains the kernel APIs related to synchronisation that have been ported or
 //! wrapped for usage by Rust code in the kernel.
 
+use crate::types::Opaque;
+
 mod arc;
 
 pub use arc::{Arc, ArcBorrow, UniqueArc};
+
+/// Represents a lockdep class. It's a wrapper around C's `lock_class_key`.
+#[repr(transparent)]
+pub struct LockClassKey(Opaque<bindings::lock_class_key>);
+
+// SAFETY: `bindings::lock_class_key` is designed to be used concurrently from multiple threads and
+// provides its own synchronization.
+unsafe impl Sync for LockClassKey {}
+
+impl LockClassKey {
+    /// Creates a new lock class key.
+    pub const fn new() -> Self {
+        Self(Opaque::uninit())
+    }
+
+    #[allow(dead_code)]
+    pub(crate) fn as_ptr(&self) -> *mut bindings::lock_class_key {
+        self.0.get()
+    }
+}
+
+/// Defines a new static lock class and returns a pointer to it.
+#[doc(hidden)]
+#[macro_export]
+macro_rules! static_lock_class {
+    () => {{
+        static CLASS: $crate::sync::LockClassKey = $crate::sync::LockClassKey::new();
+        &CLASS

rust/kernel/sync.rs line 50

Quoted 10 lines
rust/kernel/sync.rs +10 -0
+    }};
+}
+
+/// Returns the given string, if one is provided, otherwise generates one based on the source code
+/// location.
+#[doc(hidden)]
+#[macro_export]
+macro_rules! optional_name {
+    () => {
+        $crate::c_str!(core::concat!(core::file!(), ":", core::line!()))

nit: prefer ::core to core in macro.

Quoted 5 lines
rust/kernel/sync.rs +5 -0
+    };
+    ($name:literal) => {
+        $crate::c_str!($name)
+    };
+}