Skip to contentSkip to conversation

rust: sync: introduce `LockClassKey`

PATCH Superseded Wedson Almeida Filho 6 participants 42 messages Mar 30, 2023 – Apr 5, 2023

Subsystems (4)

v1 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

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

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

---
 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 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]>
---
 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
maintainer
#3 lore raw

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

Quoted 4 lines · 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.

What, if anything, are the plans to support the various lockdep annotations? Idem for the spinlock thing in the other patch I suppose.

#4 lore raw

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

Quoted 8 lines · Peter Zijlstra
Quoted 4 lines · 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.

What, if anything, are the plans to support the various lockdep annotations? Idem for the spinlock thing in the other patch I suppose.

FWIW:

* At the init stage, SpinLock and Mutex in Rust use initializers
that are aware of the lockdep, so everything (lockdep_map and lock_class) is all set up.

* At acquire or release time, Rust locks just use ffi to call C
functions that have lockdep annotations in them, so lockdep should just work.

In fact, I shared some same worry as you, so I already work on adding lockdep selftests for Rust lock APIs, will send them shortly, although they are just draft.

Regards,
Boqun

#5 lore raw

PATCH 1/2 locking/selftest: Add test infrastructure for Rust locking APIs

---
 MAINTAINERS                  |  1 +
 lib/Makefile                 |  3 +++
 lib/locking-selftest.c       |  9 +++++++++
 lib/rust_locking_selftest.rs | 12 ++++++++++++
 4 files changed, 25 insertions(+)
 create mode 100644 lib/rust_locking_selftest.rs
MAINTAINERS +1 -0
index 8d5bc223f305..c1878e18f98a 100644
@@ -12060,6 +12060,7 @@ F:	include/linux/seqlock.h
 F:	include/linux/spinlock*.h
 F:	kernel/locking/
 F:	lib/locking*.[ch]
+F:	lib/rust-locking-selftest.rs
 X:	kernel/locking/locktorture.c
 
 LOGICAL DISK MANAGER SUPPORT (LDM, Windows 2000/XP/Vista Dynamic Disks)
lib/Makefile +3 -0
index baf2821f7a00..940374c08edd 100644
@@ -148,6 +148,9 @@ obj-$(CONFIG_GENERIC_PCI_IOMAP) += pci_iomap.o
 obj-$(CONFIG_HAS_IOMEM) += iomap_copy.o devres.o
 obj-$(CONFIG_CHECK_SIGNATURE) += check_signature.o
 obj-$(CONFIG_DEBUG_LOCKING_API_SELFTESTS) += locking-selftest.o
+ifdef CONFIG_RUST
+obj-$(CONFIG_DEBUG_LOCKING_API_SELFTESTS) += rust_locking_selftest.o
+endif
 
 lib-y += logic_pio.o
 
lib/locking-selftest.c +9 -0
index 8d24279fad05..9ef3ad92bc47 100644
@@ -2854,6 +2854,11 @@ static void hardirq_deadlock_softirq_not_deadlock(void)
 	HARDIRQ_ENABLE();
 }
 
+#ifdef CONFIG_RUST
+void rust_locking_test(void);
+#else
+#define rust_locking_test()
+#endif
 void locking_selftest(void)
 {
 	/*
@@ -3010,6 +3015,10 @@ void locking_selftest(void)
 		printk("---------------------------------\n");
 		debug_locks = 1;
 	}
+
+	/* Rust locking API tests */
+	rust_locking_test();
+
 	lockdep_set_selftest_task(NULL);
 	debug_locks_silent = 0;
 }
lib/rust_locking_selftest.rs new file +12 -0
new file mode 100644
index 000000000000..61560a2f3c6b
@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Selftests for Rust locking APIs.
+
+use kernel::prelude::*;
+const __LOG_PREFIX: &[u8] = b"locking selftest\0";
+
+/// Entry point for tests.
+#[no_mangle]
+pub extern "C" fn rust_locking_test() {
+    pr_info!("Selftests for Rust locking APIs");
+}
Signature · 1 line
2.39.2
#6 lore raw

PATCH 2/2 locking/selftest: Add AA deadlock selftest for Mutex and SpinLock

---
 lib/locking-selftest.c       |  3 +-
 lib/rust_locking_selftest.rs | 99 ++++++++++++++++++++++++++++++++++++
 2 files changed, 101 insertions(+), 1 deletion(-)
lib/locking-selftest.c +2 -1
index 9ef3ad92bc47..a4830e3cc998 100644
@@ -60,6 +60,7 @@ __setup("debug_locks_verbose=", setup_debug_locks_verbose);
 #define LOCKTYPE_RTMUTEX 0x20
 #define LOCKTYPE_LL	0x40
 #define LOCKTYPE_SPECIAL 0x80
+#define LOCKTYPE_RUST	0x100
 
 static struct ww_acquire_ctx t, t2;
 static struct ww_mutex o, o2, o3;
@@ -1427,7 +1428,7 @@ static int testcase_successes;
 static int expected_testcase_failures;
 static int unexpected_testcase_failures;
 
-static void dotest(void (*testcase_fn)(void), int expected, int lockclass_mask)
+void dotest(void (*testcase_fn)(void), int expected, int lockclass_mask)
 {
 	int saved_preempt_count = preempt_count();
 #ifdef CONFIG_PREEMPT_RT
lib/rust_locking_selftest.rs +99 -0

110 lines not on this page · raw message

Signature · 1 line
2.39.2
#7 lore raw

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

In reply to Boqun Feng
Quoted 16 lines · Boqun Feng
Quoted 8 lines · Peter Zijlstra
Quoted 4 lines · 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.

What, if anything, are the plans to support the various lockdep annotations? Idem for the spinlock thing in the other patch I suppose.

FWIW:

* At the init stage, SpinLock and Mutex in Rust use initializers
that are aware of the lockdep, so everything (lockdep_map and lock_class) is all set up.

Quoted 8 lines

* At acquire or release time, Rust locks just use ffi to call C
functions that have lockdep annotations in them, so lockdep should just work.

In fact, I shared some same worry as you, so I already work on adding lockdep selftests for Rust lock APIs, will send them shortly, although they are just draft.

Needless to say, the test shows that lockdep works for deadlock detection (although currently they are only simple cases):

	[...] locking selftest: Selftests for Rust locking APIs
	[...] rust_locking_selftest::SpinLockAATest: 
	[...] 
	[...] ============================================
	[...] WARNING: possible recursive locking detected
	[...] 6.3.0-rc1-00049-gee35790bd43e-dirty #99 Not tainted
	[...] --------------------------------------------
	[...] swapper/0/0 is trying to acquire lock:
	[...] ffffffff8c603e30 (A1){+.+.}-{2:2}, at: _RNvXNtNtNtCs1t6xtuX2C8s_6kernel4sync4lock8spinlockNtB2_15SpinLockBackendNtB4_7Backend4lock+0x6/0x10
	[...] 
	[...] but task is already holding lock:
	[...] ffffffff8c603de0 (A1){+.+.}-{2:2}, at: _RNvXNtNtNtCs1t6xtuX2C8s_6kernel4sync4lock8spinlockNtB2_15SpinLockBackendNtB4_7Backend4lock+0x6/0x10
	[...] 
	[...] other info that might help us debug this:
	[...]  Possible unsafe locking scenario:
	[...] 
	[...]        CPU0
	[...]        ----
	[...]   lock(A1);
	[...]   lock(A1);
	[...] 
	[...]  *** DEADLOCK ***
	[...] 
	[...]  May be due to missing lock nesting notation
	[...] 
	[...] 1 lock held by swapper/0/0:
	[...]  #0: ffffffff8c603de0 (A1){+.+.}-{2:2}, at: _RNvXNtNtNtCs1t6xtuX2C8s_6kernel4sync4lock8spinlockNtB2_15SpinLockBackendNtB4_7Backend4lock+0x6/0x10
	[...] 
	[...] stack backtrace:
	[...] CPU: 0 PID: 0 Comm: swapper/0 Not tainted 6.3.0-rc1-00049-gee35790bd43e-dirty #99
	[...] Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS Arch Linux 1.16.1-1-1 04/01/2014
	[...] Call Trace:
	[...]  <TASK>
	[...]  dump_stack_lvl+0x6d/0xa0
	[...]  __lock_acquire+0x825/0x2e20
	[...]  ? __lock_acquire+0x626/0x2e20
	[...]  ? prb_read_valid+0x24/0x50
	[...]  ? printk_get_next_message+0xf6/0x380
	[...]  ? _RNvXNtNtNtCs1t6xtuX2C8s_6kernel4sync4lock8spinlockNtB2_15SpinLockBackendNtB4_7Backend4lock+0x6/0x10
	[...]  lock_acquire+0x109/0x2c0
	[...]  ? _RNvXNtNtNtCs1t6xtuX2C8s_6kernel4sync4lock8spinlockNtB2_15SpinLockBackendNtB4_7Backend4lock+0x6/0x10
	[...]  _raw_spin_lock+0x2e/0x40
	[...]  ? _RNvXNtNtNtCs1t6xtuX2C8s_6kernel4sync4lock8spinlockNtB2_15SpinLockBackendNtB4_7Backend4lock+0x6/0x10
	[...]  _RNvXNtNtNtCs1t6xtuX2C8s_6kernel4sync4lock8spinlockNtB2_15SpinLockBackendNtB4_7Backend4lock+0x6/0x10
	[...]  _RNvXCsaDWbe1gW6fC_21rust_locking_selftestNtB2_14SpinLockAATestNtB2_8LockTest4test+0xa5/0xe0
	[...]  ? prb_read_valid+0x24/0x50
	[...]  dotest+0x5a/0x8d0
	[...]  rust_locking_test+0xf8/0x210
	[...]  ? _printk+0x58/0x80
	[...]  ? local_lock_release+0x60/0x60
	[...]  locking_selftest+0x328f/0x32b0
	[...]  start_kernel+0x285/0x420
	[...]  secondary_startup_64_no_verify+0xe1/0xeb
	[...]  </TASK>
	[...]   ok  | lockclass mask: 100, debug_locks: 0, expected: 0

Regards,
Boqun

Quoted 2 lines

Regards,
Boqun

maintainer
#8 lore raw

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

In reply to Boqun Feng
Quoted 12 lines · Boqun Feng
Quoted 8 lines · Peter Zijlstra
Quoted 4 lines · 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.

What, if anything, are the plans to support the various lockdep annotations? Idem for the spinlock thing in the other patch I suppose.

FWIW:

Quoted 8 lines

* At the init stage, SpinLock and Mutex in Rust use initializers
that are aware of the lockdep, so everything (lockdep_map and lock_class) is all set up.

* At acquire or release time, Rust locks just use ffi to call C
functions that have lockdep annotations in them, so lockdep should just work.

ffi is what the C++ world calls RAII ?

But yes, I got that far, but I wondered about things like spin_lock_nested(&foo, SINGLE_DEPTH_NESTING) and other such 'advanced' annotations.

Surely we're going to be needing them at some point. I suppose you can do the single depth nesting one with a special guard type (or whatever you call that in the rust world) ?

#9 lore raw

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

Quoted 17 lines · Peter Zijlstra
Quoted 16 lines · Boqun Feng
Quoted 8 lines · Peter Zijlstra
Quoted 4 lines · 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.

What, if anything, are the plans to support the various lockdep annotations? Idem for the spinlock thing in the other patch I suppose.

FWIW:

* At the init stage, SpinLock and Mutex in Rust use initializers
that are aware of the lockdep, so everything (lockdep_map and lock_class) is all set up.

Quoted 6 lines
Quoted 4 lines

* At acquire or release time, Rust locks just use ffi to call C
functions that have lockdep annotations in them, so lockdep should just work.

ffi is what the C++ world calls RAII ?

No, ffi is 'foreign function interface', it just means that the caller will use the same ABI as the callee.

Quoted 7 lines

But yes, I got that far, but I wondered about things like spin_lock_nested(&foo, SINGLE_DEPTH_NESTING) and other such 'advanced' annotations.

Surely we're going to be needing them at some point. I suppose you can do the single depth nesting one with a special guard type (or whatever you call that in the rust world) ?

I haven't looked at all the advanced annotations, but something like spin_lock_nested/mutex_lock_nested can be exposed as a lock_nested() associated function of the Lock type, so one would do:

let guard = my_mutex.lock_nested(SINGLE_DEPTH_NESTING); // Do something with data protected by my_mutex.

maintainer
#10 lore raw

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

Quoted 36 lines · On Mon, 3 Apr 2023 10:50:09 -0300 Wedson Almeida Filho <[email protected]>…
Quoted 17 lines · Peter Zijlstra
Quoted 16 lines · Boqun Feng
Quoted 8 lines · Peter Zijlstra
Quoted 4 lines · 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.

What, if anything, are the plans to support the various lockdep annotations? Idem for the spinlock thing in the other patch I suppose.

FWIW:

* At the init stage, SpinLock and Mutex in Rust use initializers
that are aware of the lockdep, so everything (lockdep_map and lock_class) is all set up.

Quoted 6 lines
Quoted 4 lines

* At acquire or release time, Rust locks just use ffi to call C
functions that have lockdep annotations in them, so lockdep should just work.

ffi is what the C++ world calls RAII ?

No, ffi is 'foreign function interface', it just means that the caller will use the same ABI as the callee.

Quoted 7 lines

But yes, I got that far, but I wondered about things like spin_lock_nested(&foo, SINGLE_DEPTH_NESTING) and other such 'advanced' annotations.

Surely we're going to be needing them at some point. I suppose you can do the single depth nesting one with a special guard type (or whatever you call that in the rust world) ?

Quoted 6 lines

I haven't looked at all the advanced annotations, but something like spin_lock_nested/mutex_lock_nested can be exposed as a lock_nested() associated function of the Lock type, so one would do:

let guard = my_mutex.lock_nested(SINGLE_DEPTH_NESTING); // Do something with data protected by my_mutex.

I don't think an additional function would work. It's not okay to perform both nested locking and non-nested locking on the same lock because non-nested locking will give you a mutable reference, and getting another reference from nested lock guard would violate aliasing rules.

A new lock type would be needed for nested locking, and guard of it can only hand out immutable reference.

Best,
Gary

#11 lore raw

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

Quoted 43 lines · Gary Guo
Quoted 40 lines · On Mon, 3 Apr 2023 10:50:09 -0300 Wedson Almeida Filho <[email protected]>…
Quoted 17 lines · Peter Zijlstra
Quoted 16 lines · Boqun Feng
Quoted 8 lines · Peter Zijlstra
Quoted 4 lines · 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.

What, if anything, are the plans to support the various lockdep annotations? Idem for the spinlock thing in the other patch I suppose.

FWIW:

* At the init stage, SpinLock and Mutex in Rust use initializers
that are aware of the lockdep, so everything (lockdep_map and lock_class) is all set up.

Quoted 6 lines
Quoted 4 lines

* At acquire or release time, Rust locks just use ffi to call C
functions that have lockdep annotations in them, so lockdep should just work.

ffi is what the C++ world calls RAII ?

No, ffi is 'foreign function interface', it just means that the caller will use the same ABI as the callee.

Quoted 7 lines

But yes, I got that far, but I wondered about things like spin_lock_nested(&foo, SINGLE_DEPTH_NESTING) and other such 'advanced' annotations.

Surely we're going to be needing them at some point. I suppose you can do the single depth nesting one with a special guard type (or whatever you call that in the rust world) ?

I haven't looked at all the advanced annotations, but something like spin_lock_nested/mutex_lock_nested can be exposed as a lock_nested() associated function of the Lock type, so one would do:

Quoted 5 lines
Quoted 2 lines

let guard = my_mutex.lock_nested(SINGLE_DEPTH_NESTING); // Do something with data protected by my_mutex.

I don't think an additional function would work. It's not okay to perform both nested locking and non-nested locking on the same lock

Note that lock_nested() here is simply a lockdep concept, it means locking nested under the same lock class (key), not lock instance, for example:

	spinlock_t X1;
	spinlock_t X2;

	// X1 and X2 are of the same lock class X
	spin_lock(&X1);
	spin_lock(&X2); // lockdep will report a deadlock.

	// However, if we know that X1 and X2 has some ordering to lock,
	// e.g. X1 is the lock for a directory and X2 is the lock for
	// the file in the directory, we can
	spin_lock(&X1);
	spin_lock_nested(&X2, SINGLE_DEPTH_NESTING);

	// and lockdep won't complain.

There is some design space here for Rust, since we may be able to put the nested information in the type.

Regards,
Boqun

Quoted 9 lines

because non-nested locking will give you a mutable reference, and getting another reference from nested lock guard would violate aliasing rules.

A new lock type would be needed for nested locking, and guard of it can only hand out immutable reference.

Best,
Gary

#12 lore raw

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

In reply to Peter Zijlstra
Quoted 17 lines · Peter Zijlstra
Quoted 16 lines · Boqun Feng
Quoted 8 lines · Peter Zijlstra
Quoted 4 lines · 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.

What, if anything, are the plans to support the various lockdep annotations? Idem for the spinlock thing in the other patch I suppose.

FWIW:

* At the init stage, SpinLock and Mutex in Rust use initializers
that are aware of the lockdep, so everything (lockdep_map and lock_class) is all set up.

Quoted 7 lines
Quoted 4 lines

* At acquire or release time, Rust locks just use ffi to call C
functions that have lockdep annotations in them, so lockdep should just work.

ffi is what the C++ world calls RAII ?

ffi is foreign function interface, it means calling a C function from Rust. Sorry if I make things confusing ;-)

Quoted 4 lines

But yes, I got that far, but I wondered about things like spin_lock_nested(&foo, SINGLE_DEPTH_NESTING) and other such 'advanced' annotations.

Right, I haven't really thought through them, but I think it's easy to add them later (famous later words).

Quoted 3 lines

Surely we're going to be needing them at some point. I suppose you can do the single depth nesting one with a special guard type (or whatever you call that in the rust world) ?

or a different method for Lock:

	impl Lock { // implementation block for type `Lock`
	//                 v function is called via a.lock_nested(SINGLE_DEPTH_NESTING), a is a Lock
	    fn lock_nested(&self, level: i32) -> Guard<..> {
	//  ^ defines a function           ^ returns a guard

	        ..  
	    }
	}

since Rust side just uses the same function to unlock as C side, so a normal Guard type suffices, because we don't treat nested lock differently at unlock time. But if we were to add some more checking at compile time, we could have a slight different Guard or something.

Regards,
Boqun

#13 lore raw

PATCH 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]>
---
 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
#14 lore raw

PATCH 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]>
---
 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
#15 lore raw

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

---
 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
#16 lore raw

PATCH 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]>
---
 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
#17 lore raw

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

---
 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
maintainer Reviewed-by on v1 8/13
#18 lore raw

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

Quoted 7 lines · On Thu, 30 Mar 2023 01:39:49 -0300 Wedson Almeida Filho <[email protected]>…

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.

Quoted 131 lines
---
 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`.
#19 lore raw

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

---
 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
#20 lore raw

PATCH 10/13 rust: introduce `Task::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.

---
 rust/helpers.c      |  6 ++++
 rust/kernel/task.rs | 83 ++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 88 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/task.rs +82 -1

104 lines not on this page · raw message

Signature · 1 line
2.34.1
maintainer
#21 lore raw

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

Quoted 98 lines · On Thu, 30 Mar 2023 01:39:51 -0300 Wedson Almeida Filho <[email protected]>…

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.

---
 rust/helpers.c      |  6 ++++
 rust/kernel/task.rs | 83 ++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 88 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/task.rs +45 -1
index 8d7a8222990f..8b2b56ba9c6d 100644
@@ -5,7 +5,7 @@
 //! 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};
 
 /// Wraps the kernel's `struct task_struct`.
 ///
@@ -13,6 +13,46 @@ 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:
+///
+/// ```
+/// use kernel::task::Task;
+///
+/// let pid = Task::current().pid();
+/// ```
+///
+/// Getting the PID of the current process, also zero additional cost:
+///
+/// ```
+/// use kernel::task::Task;
+///
+/// let pid = Task::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, ARef};
+///
+/// struct State {
+///     creator: ARef<Task>,
+///     index: u32,
+/// }
+///
+/// impl State {
+///     fn new() -> Self {
+///         Self {
+///             creator: Task::current().into(),
+///             index: 0,
+///         }
+///     }
+/// }
+/// ```
 #[repr(transparent)]
 pub struct Task(pub(crate) UnsafeCell<bindings::task_struct>);
 
@@ -25,6 +65,20 @@ unsafe impl Sync for Task {}
 type Pid = bindings::pid_t;
 
 impl Task {
+    /// Returns a task reference for the currently executing task/thread.
+    pub fn current<'a>() -> TaskRef<'a> {
+        // SAFETY: Just an FFI call with no additional safety requirements.
+        let ptr = unsafe { bindings::get_current() };

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

Quoted 10 lines
rust/kernel/task.rs +10 -0
+
+        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,
+        }
+    }
+

I don't think this API is sound, as you can do &*Task::current() and get a &'static Task, which is very problematic.

A sound API would be

	pub fn with_current<R>(f: imp FnOnce(&Task) -> R) -> R { ... }

(which also is how thread local works in Rust)

You would have to write Task::with_current(|cur| cur.pid()) though, which unfortunately is a bit less ergonomic.

Best,
Gary

#22 lore raw

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

Quoted 119 lines · Gary Guo
Quoted 98 lines · On Thu, 30 Mar 2023 01:39:51 -0300 Wedson Almeida Filho <[email protected]>…

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.

---
  rust/helpers.c      |  6 ++++
  rust/kernel/task.rs | 83 ++++++++++++++++++++++++++++++++++++++++++++-
  2 files changed, 88 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/task.rs +45 -1
index 8d7a8222990f..8b2b56ba9c6d 100644
@@ -5,7 +5,7 @@
  //! 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};
 
  /// Wraps the kernel's `struct task_struct`.
  ///
@@ -13,6 +13,46 @@ 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:
+///
+/// ```
+/// use kernel::task::Task;
+///
+/// let pid = Task::current().pid();
+/// ```
+///
+/// Getting the PID of the current process, also zero additional cost:
+///
+/// ```
+/// use kernel::task::Task;
+///
+/// let pid = Task::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, ARef};
+///
+/// struct State {
+///     creator: ARef<Task>,
+///     index: u32,
+/// }
+///
+/// impl State {
+///     fn new() -> Self {
+///         Self {
+///             creator: Task::current().into(),
+///             index: 0,
+///         }
+///     }
+/// }
+/// ```
  #[repr(transparent)]
  pub struct Task(pub(crate) UnsafeCell<bindings::task_struct>);
 
@@ -25,6 +65,20 @@ unsafe impl Sync for Task {}
  type Pid = bindings::pid_t;
 
  impl Task {
+    /// Returns a task reference for the currently executing task/thread.
+    pub fn current<'a>() -> TaskRef<'a> {
+        // SAFETY: Just an FFI call with no additional safety requirements.
+        let ptr = unsafe { bindings::get_current() };

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

Quoted 10 lines
rust/kernel/task.rs +10 -0
+
+        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,
+        }
+    }
+

I don't think this API is sound, as you can do &*Task::current() and get a &'static Task, which is very problematic.

A sound API would be

	pub fn with_current<R>(f: imp FnOnce(&Task) -> R) -> R { ... }
Quoted 7 lines

(which also is how thread local works in Rust)

You would have to write Task::with_current(|cur| cur.pid()) though, which unfortunately is a bit less ergonomic.

Best,
Gary

This is true, unfortunately. It would be possible to write a macro with a more similar API to the current implementation.

#23 lore raw

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

In reply to Gary Guo

Gary, thanks for reviewing!

Quoted 3 lines · Gary Guo

I don't think this API is sound, as you can do &*Task::current() and get a &'static Task, which is very problematic.

One thing that isn't clear to me is: how do you get a 'static lifetime in the example above?

Altough TaskRef does have an arbitrary lifetime param, that's not the lifetime that the returned Task reference gets. For illustration, I've explicitly added a lifetime 'a in the impl below:

impl Deref for TaskRef<'_> {
    type Target = Task;
    fn deref(&'a self) -> &'a Self::Target {
        self.task
    }
}

Which means that the borrow of the TaskRef you use to call deref must outlive the returned Task.

So how do you get a TaskRef with a static lifetime to begin with? Or is there another trick to get the &'static Task that I can't see?

Thanks,
-Wedson

maintainer
#24 lore raw

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

Quoted 21 lines · On Sat, 1 Apr 2023 01:09:18 -0300 Wedson Almeida Filho <[email protected]>…

Gary, thanks for reviewing!

Quoted 3 lines · Gary Guo

I don't think this API is sound, as you can do &*Task::current() and get a &'static Task, which is very problematic.

One thing that isn't clear to me is: how do you get a 'static lifetime in the example above?

Altough TaskRef does have an arbitrary lifetime param, that's not the lifetime that the returned Task reference gets. For illustration, I've explicitly added a lifetime 'a in the impl below:

impl Deref for TaskRef<'_> {
    type Target = Task;
    fn deref(&'a self) -> &'a Self::Target {
        self.task
    }
}
Quoted 8 lines

Which means that the borrow of the TaskRef you use to call deref must outlive the returned Task.

So how do you get a TaskRef with a static lifetime to begin with? Or is there another trick to get the &'static Task that I can't see?

Thanks,
-Wedson

Hi Wedson,

My apologies for the confusion. &*Task::current() is not sufficient. I typed too quick without double checking.

However it is still true that TaskRef<'static> is unsound, and it can be retrieved from current(). The missing step is &'static TaskRef<'static>.

So you can write &*Box::leak(Box::try_new(Task::current()).unwrap()) and get &'static Task.

Best,
Gary

#25 lore raw

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

---
 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 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]>
---
 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
maintainer
#27 lore raw

Re: [PATCH 12/13] rust: sync: introduce `CondVar`

Quoted 10 lines · 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.

rust/kernel/sync/condvar.rs line 27

Quoted 7 lines
rust/kernel/sync/condvar.rs new file +7 -0
+/// A conditional variable.
+///
+/// Exposes the kernel's [`struct wait_queue_head`] as a condition variable. It allows the caller to
+/// atomically release the given lock and go to sleep. It reacquires the lock when it wakes up. And
+/// it wakes up when notified by another thread (via [`CondVar::notify_one`] or
+/// [`CondVar::notify_all`]) or because the thread received a signal. It may also wake up
+/// spuriously.

Urgh so wide :-/

But no, threads can *always* and for any reason, have spurious wakeups.

Also, is this hard tied to mutex? If so, you should probably use swait instead of wait.

#28 lore raw

Re: [PATCH 12/13] rust: sync: introduce `CondVar`

Quoted 11 lines · Peter Zijlstra
Quoted 9 lines · 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.

Quoted 9 lines

rust/kernel/sync/condvar.rs line 27

Quoted 7 lines
rust/kernel/sync/condvar.rs new file +7 -0
+/// A conditional variable.
+///
+/// Exposes the kernel's [`struct wait_queue_head`] as a condition variable. It allows the caller to
+/// atomically release the given lock and go to sleep. It reacquires the lock when it wakes up. And
+/// it wakes up when notified by another thread (via [`CondVar::notify_one`] or
+/// [`CondVar::notify_all`]) or because the thread received a signal. It may also wake up
+/// spuriously.

Urgh so wide :-/

Thanks for reviewing :)

Quoted 1 line

But no, threads can *always* and for any reason, have spurious wakeups.

I don't believe I said otherwise. Is there anything in the text above you'd like to see changed?

Quoted 2 lines

Also, is this hard tied to mutex? If so, you should probably use swait instead of wait.

This is not tied to mutex, it works with any lock.

Cheers,
-Wedson

maintainer
#29 lore raw

Re: [PATCH 12/13] rust: sync: introduce `CondVar`

In reply to Wedson Almeida Filho
Quoted 18 lines · Wedson Almeida Filho
rust/kernel/sync/condvar.rs new file +18 -0
+impl CondVar {
+    /// Constructs a new condvar initialiser.
+    #[allow(clippy::new_ret_no_self)]
+    pub fn new(name: &'static CStr, key: &'static LockClassKey) -> impl PinInit<Self> {
+        pin_init!(Self {
+            _pin: PhantomPinned,
+            // SAFETY: `__init_waitqueue_head` initialises the waitqueue head, and both `name` and
+            // `key` have static lifetimes so they live indefinitely.
+            wait_list <- unsafe {
+                Opaque::ffi_init2(
+                    bindings::__init_waitqueue_head,
+                    name.as_char_ptr(),
+                    key.as_ptr(),
+                )
+            },
+        })
+    }
+

rust/kernel/sync/condvar.rs line 119

Quoted 10 lines
rust/kernel/sync/condvar.rs new file +10 -0
+    fn wait_internal<T: ?Sized, B: Backend>(&self, wait_state: u32, guard: &mut Guard<'_, T, B>) {
+        let wait = Opaque::<bindings::wait_queue_entry>::uninit();
+
+        // SAFETY: `wait` points to valid memory.
+        unsafe { bindings::init_wait(wait.get()) };
+
+        // SAFETY: Both `wait` and `wait_list` point to valid memory.
+        unsafe {
+            bindings::prepare_to_wait_exclusive(self.wait_list.get(), wait.get(), wait_state as _)
+        };

I can't read this rust gunk, but where is the condition test gone?

Also, where is the loop gone to?

Quoted 59 lines
rust/kernel/sync/condvar.rs new file +59 -0
+
+        // SAFETY: No arguments, switches to another thread.
+        guard.do_unlocked(|| unsafe { bindings::schedule() });
+
+        // SAFETY: Both `wait` and `wait_list` point to valid memory.
+        unsafe { bindings::finish_wait(self.wait_list.get(), wait.get()) };
+    }
+
+    /// Releases the lock and waits for a notification in interruptible mode.
+    ///
+    /// Atomically releases the given lock (whose ownership is proven by the guard) and puts the
+    /// thread to sleep, reacquiring the lock on wake up. It wakes up when notified by
+    /// [`CondVar::notify_one`] or [`CondVar::notify_all`], or when the thread receives a signal.
+    /// It may also wake up spuriously.
+    ///
+    /// Returns whether there is a signal pending.
+    #[must_use = "wait returns if a signal is pending, so the caller must check the return value"]
+    pub fn wait<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) -> bool {
+        self.wait_internal(bindings::TASK_INTERRUPTIBLE, guard);
+        Task::current().signal_pending()
+    }
+
+    /// Releases the lock and waits for a notification in uninterruptible mode.
+    ///
+    /// Similar to [`CondVar::wait`], except that the wait is not interruptible. That is, the
+    /// thread won't wake up due to signals. It may, however, wake up supirously.
+    pub fn wait_uninterruptible<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) {
+        self.wait_internal(bindings::TASK_UNINTERRUPTIBLE, guard)
+    }
+
+    /// Calls the kernel function to notify the appropriate number of threads with the given flags.
+    fn notify(&self, count: i32, flags: u32) {
+        // SAFETY: `wait_list` points to valid memory.
+        unsafe {
+            bindings::__wake_up(
+                self.wait_list.get(),
+                bindings::TASK_NORMAL,
+                count,
+                flags as _,
+            )
+        };
+    }
+
+    /// Wakes a single waiter up, if any.
+    ///
+    /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost
+    /// completely (as opposed to automatically waking up the next waiter).
+    pub fn notify_one(&self) {
+        self.notify(1, 0);
+    }
+
+    /// Wakes all waiters up, if any.
+    ///
+    /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost
+    /// completely (as opposed to automatically waking up the next waiter).
+    pub fn notify_all(&self) {
+        self.notify(0, 0);
+    }
+}
#30 lore raw

Re: [PATCH 12/13] rust: sync: introduce `CondVar`

Quoted 15 lines · Peter Zijlstra

rust/kernel/sync/condvar.rs line 119

Quoted 10 lines · Wedson Almeida Filho
rust/kernel/sync/condvar.rs new file +10 -0
+    fn wait_internal<T: ?Sized, B: Backend>(&self, wait_state: u32, guard: &mut Guard<'_, T, B>) {
+        let wait = Opaque::<bindings::wait_queue_entry>::uninit();
+
+        // SAFETY: `wait` points to valid memory.
+        unsafe { bindings::init_wait(wait.get()) };
+
+        // SAFETY: Both `wait` and `wait_list` point to valid memory.
+        unsafe {
+            bindings::prepare_to_wait_exclusive(self.wait_list.get(), wait.get(), wait_state as _)
+        };

I can't read this rust gunk, but where is the condition test gone?

Quoted 1 line

Also, where is the loop gone to?

They're both at the caller. The usage of condition variables is something like:

while guard.value != v {
    condvar.wait_uninterruptible(&mut guard);
}

(Note that this is not specific to the kernel or to Rust: this is how condvars work in general. You'll find this in any textbook on the topic.)

In the implementation of wait_internal(), we add the local wait entry to the wait queue _before_ releasing the lock (i.e., before the test result can change), so we guarantee that we don't miss wake up attempts.

Thanks,
-Wedson

maintainer
#31 lore raw

Re: [PATCH 12/13] rust: sync: introduce `CondVar`

Quoted 24 lines · Wedson Almeida Filho
Quoted 15 lines · Peter Zijlstra

rust/kernel/sync/condvar.rs line 119

Quoted 10 lines · Wedson Almeida Filho
rust/kernel/sync/condvar.rs new file +10 -0
+    fn wait_internal<T: ?Sized, B: Backend>(&self, wait_state: u32, guard: &mut Guard<'_, T, B>) {
+        let wait = Opaque::<bindings::wait_queue_entry>::uninit();
+
+        // SAFETY: `wait` points to valid memory.
+        unsafe { bindings::init_wait(wait.get()) };
+
+        // SAFETY: Both `wait` and `wait_list` point to valid memory.
+        unsafe {
+            bindings::prepare_to_wait_exclusive(self.wait_list.get(), wait.get(), wait_state as _)
+        };

I can't read this rust gunk, but where is the condition test gone?

Quoted 1 line

Also, where is the loop gone to?

They're both at the caller. The usage of condition variables is something like:

while guard.value != v {
    condvar.wait_uninterruptible(&mut guard);
}
Quoted 6 lines

(Note that this is not specific to the kernel or to Rust: this is how condvars work in general. You'll find this in any textbook on the topic.)

In the implementation of wait_internal(), we add the local wait entry to the wait queue _before_ releasing the lock (i.e., before the test result can change), so we guarantee that we don't miss wake up attempts.

Ah, so you've not yet been exposed to the wonderful 'feature' where pthread_cond_timedwait() gets called with .mutex=NULL and people expect things to just work :/ (luckily not accepted by the majority of implementations)

Or a little more devious, calling signal and not holding the same mutex.

But then yes, I suppose it should work. I just got alarm bells going off because I see prepare_to_wait without an obvious loop around it.

#32 lore raw

Re: [PATCH 12/13] rust: sync: introduce `CondVar`

Quoted 28 lines · Peter Zijlstra
Quoted 27 lines · Wedson Almeida Filho
Quoted 15 lines · Peter Zijlstra

rust/kernel/sync/condvar.rs line 119

Quoted 10 lines · Wedson Almeida Filho
rust/kernel/sync/condvar.rs new file +10 -0
+    fn wait_internal<T: ?Sized, B: Backend>(&self, wait_state: u32, guard: &mut Guard<'_, T, B>) {
+        let wait = Opaque::<bindings::wait_queue_entry>::uninit();
+
+        // SAFETY: `wait` points to valid memory.
+        unsafe { bindings::init_wait(wait.get()) };
+
+        // SAFETY: Both `wait` and `wait_list` point to valid memory.
+        unsafe {
+            bindings::prepare_to_wait_exclusive(self.wait_list.get(), wait.get(), wait_state as _)
+        };

I can't read this rust gunk, but where is the condition test gone?

Quoted 1 line

Also, where is the loop gone to?

They're both at the caller. The usage of condition variables is something like:

while guard.value != v {
    condvar.wait_uninterruptible(&mut guard);
}

(Note that this is not specific to the kernel or to Rust: this is how condvars work in general. You'll find this in any textbook on the topic.)

Quoted 8 lines
Quoted 3 lines

In the implementation of wait_internal(), we add the local wait entry to the wait queue _before_ releasing the lock (i.e., before the test result can change), so we guarantee that we don't miss wake up attempts.

Ah, so you've not yet been exposed to the wonderful 'feature' where pthread_cond_timedwait() gets called with .mutex=NULL and people expect things to just work :/ (luckily not accepted by the majority of implementations)

Rust doesn't have this problem: a Guard cannot exist without a lock, and one cannot call wait or wait_uninterruptible without a Guard.

Quoted 1 line

Or a little more devious, calling signal and not holding the same mutex.

We don't require that callers hold the lock while singaling. If they signal when the condition isn't satisfied (with or without the lock held, it doesn't matter), it will just look like a spurious signal to the waiting thread.

Quoted 2 lines

I just got alarm bells going off because I see prepare_to_wait without an obvious loop around it.

Fair enough, we do need a loop.

#33 lore raw

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

---
 rust/kernel/sync.rs           |   2 +
 rust/kernel/sync/lock.rs      |   2 +-
 rust/kernel/sync/locked_by.rs | 126 ++++++++++++++++++++++++++++++++++
 3 files changed, 129 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 +126 -0

126 lines not on this page · raw message

Signature · 1 line
2.34.1
#34 lore raw

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

Quoted 101 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.

---
  rust/kernel/sync.rs           |   2 +
  rust/kernel/sync/lock.rs      |   2 +-
  rust/kernel/sync/locked_by.rs | 126 ++++++++++++++++++++++++++++++++++
  3 files changed, 129 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 +51 -0
new file mode 100644
index 000000000000..cbfd4e84b770
@@ -0,0 +1,126 @@
+// 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
+/// 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.
+///
+/// # 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();

rust/kernel/sync/locked_by.rs line 61

Quoted 10 lines
rust/kernel/sync/locked_by.rs new file +10 -0
+///     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);

Missing deref (*) in front of guard.

Quoted 66 lines
rust/kernel/sync/locked_by.rs new file +65 -1
+///     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
+    /// 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 {
+        Self {
+            owner: owner.data.get(),
+            data: UnsafeCell::new(data),
+        }
+    }
+}
+
+impl<T: ?Sized, U: ?Sized> LockedBy<T, U> {
+    /// Returns a reference to the protected data when the caller provides evidence (via a
+    /// reference) that the owner is locked.
+    pub fn access<'a>(&'a self, owner: &'a U) -> &'a T {
+        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 {
+        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() }
+    }
+}
--
Quoted 2 lines

2.34.1

What happens if the the protected data U is a ZST? Then the address comparing will not work, since all ZST references have the same address. For example:

     struct Outer {
         mtx: Mutex<()>,
         inners: Vec<Inner>,
     }

     struct Inner {
         count: LockedBy<usize, ()>,
     }

     fn evil(inner: &Inner) {
         // can create two mutable references at the same time:
         let a = inner.count.access_mut(&mut ());
         let b = inner.count.access_mut(&mut ());
         core::mem::swap(a, b);
     }

Maybe prevent this by checking for assert!(mem::size_of::<U>() != 0); in the new function? Though I am not sure if a ZST is the only way for values to share addresses.

--
Cheers,
Benno

#35 lore raw

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

Quoted 4 lines · Benno Lossin

What happens if the the protected data U is a ZST? Then the address comparing will not work, since all ZST references have the same address. For example:

Quoted 15 lines
      struct Outer {
          mtx: Mutex<()>,
          inners: Vec<Inner>,
      }

      struct Inner {
          count: LockedBy<usize, ()>,
      }

      fn evil(inner: &Inner) {
          // can create two mutable references at the same time:
          let a = inner.count.access_mut(&mut ());
          let b = inner.count.access_mut(&mut ());
          core::mem::swap(a, b);
      }

Sorry the example I provided does not actually work, since &mut () refers to a place on the stack. I found a new example that shows ZSTs are still problematic:

     struct Outer {
         mtx1: Mutex<()>,
         mtx2: Mutex<()>,
         inners: Vec<Inner>,
     }

     struct Inner {
         count: LockedBy<usize, ()>,
     }

     fn new_inner(outer: &Outer) -> Inner {
         Inner { count: LockedBy::new(&outer.mtx1, 0) }
     }

     fn evil(outer: &Outer) {
         let inner = outer.inners.get(0).unwrap();
         let mut guard1 = outer.mtx1.lock();
         let mut guard2 = outer.mtx2.lock();
	// The pointee of `guard1` and `guard2` have the same address.
         let ref1 = inner.count.access_mut(&mut *guard1);
         let ref2 = inner.count.access_mut(&mut *guard2);
         mem::swap(ref1, ref2);
     }

--
Cheers,
Benno

#36 lore raw

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

Quoted 17 lines · Benno Lossin

On 30.03.23 13:28, Benno Lossin wrote:

     struct Outer {
         mtx1: Mutex<()>,
         mtx2: Mutex<()>,
         inners: Vec<Inner>,
     }

     struct Inner {
         count: LockedBy<usize, ()>,
     }

     fn new_inner(outer: &Outer) -> Inner {
         Inner { count: LockedBy::new(&outer.mtx1, 0) }
     }

     fn evil(outer: &Outer) {
Quoted 8 lines
         let inner = outer.inners.get(0).unwrap();
         let mut guard1 = outer.mtx1.lock();
         let mut guard2 = outer.mtx2.lock();
        // The pointee of `guard1` and `guard2` have the same address.
         let ref1 = inner.count.access_mut(&mut *guard1);
         let ref2 = inner.count.access_mut(&mut *guard2);
         mem::swap(ref1, ref2);
     }

This doesn't reproduce the issue because mtx2 itself is not a ZST (it contains a struct mutex before the data it protects).

Something like the following should reproduce it though:

    struct Outer {
         mtx1: Mutex<()>,
         zst: (),
     }

     fn evil(outer: &Outer) {
         let lb = LockedBy::new(&outer.mtx1, 0u8);
         let value = lb.access(&outer.zst);
         // Accessing "value" without holding `mtx1`.
         pr_info!("{}", *value);
     }
#37 lore raw

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

Quoted 32 lines · Wedson Almeida Filho
Quoted 17 lines · Benno Lossin

On 30.03.23 13:28, Benno Lossin wrote:

      struct Outer {
          mtx1: Mutex<()>,
          mtx2: Mutex<()>,
          inners: Vec<Inner>,
      }

      struct Inner {
          count: LockedBy<usize, ()>,
      }

      fn new_inner(outer: &Outer) -> Inner {
          Inner { count: LockedBy::new(&outer.mtx1, 0) }
      }

      fn evil(outer: &Outer) {
Quoted 8 lines
          let inner = outer.inners.get(0).unwrap();
          let mut guard1 = outer.mtx1.lock();
          let mut guard2 = outer.mtx2.lock();
         // The pointee of `guard1` and `guard2` have the same address.
          let ref1 = inner.count.access_mut(&mut *guard1);
          let ref2 = inner.count.access_mut(&mut *guard2);
          mem::swap(ref1, ref2);
      }

This doesn't reproduce the issue because mtx2 itself is not a ZST (it contains a struct mutex before the data it protects).

Something like the following should reproduce it though:

Quoted 11 lines
     struct Outer {
          mtx1: Mutex<()>,
          zst: (),
      }

      fn evil(outer: &Outer) {
          let lb = LockedBy::new(&outer.mtx1, 0u8);
          let value = lb.access(&outer.zst);
          // Accessing "value" without holding `mtx1`.
          pr_info!("{}", *value);
      }

You are correct, but in your example you also cannot be sure that it works, since the layout of the Mutex and Outer is repr(Rust). And so you cannot be sure that zst has the same address as value inside of the Mutex (since the struct mutex could be in between). But regardless, lets just deny ZSTs in LockedBy since the fix is easy and it would be weird to put a ZST in a lock in the first place. (Not that you have argued against it)

--
Cheers,
Benno

#38 lore raw

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

In reply to Benno Lossin

Hey Benno,

Thanks for reviewing!

Quoted 107 lines · Benno Lossin
Quoted 105 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.

---
  rust/kernel/sync.rs           |   2 +
  rust/kernel/sync/lock.rs      |   2 +-
  rust/kernel/sync/locked_by.rs | 126 ++++++++++++++++++++++++++++++++++
  3 files changed, 129 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 +55 -0
new file mode 100644
index 000000000000..cbfd4e84b770
@@ -0,0 +1,126 @@
+// 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
+/// 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.
+///
+/// # 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);
+/// }
+///
Quoted 8 lines

rust/kernel/sync/locked_by.rs line 61

Quoted 6 lines
rust/kernel/sync/locked_by.rs new file +6 -0
+/// /// 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);

Missing deref (*) in front of guard.

Deref coercion obviates the need for an explicit dereference. This works as is.

Quoted 63 lines
Quoted 63 lines
rust/kernel/sync/locked_by.rs new file +63 -0
+///     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
+    /// 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 {
+        Self {
+            owner: owner.data.get(),
+            data: UnsafeCell::new(data),
+        }
+    }
+}
+
+impl<T: ?Sized, U: ?Sized> LockedBy<T, U> {
+    /// Returns a reference to the protected data when the caller provides evidence (via a
+    /// reference) that the owner is locked.
+    pub fn access<'a>(&'a self, owner: &'a U) -> &'a T {
+        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 {
+        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() }
Quoted 8 lines
Quoted 5 lines
rust/kernel/sync/locked_by.rs new file +2 -1
+    }
+}
--

2.34.1

What happens if the the protected data U is a ZST? Then the address comparing will not work, since all ZST references have the same address.

Indeed SZTs are problematic. I'll add a restriction to rule them out.

Quoted 18 lines

For example:

     struct Outer {
         mtx: Mutex<()>,
         inners: Vec<Inner>,
     }

     struct Inner {
         count: LockedBy<usize, ()>,
     }

     fn evil(inner: &Inner) {
         // can create two mutable references at the same time:
         let a = inner.count.access_mut(&mut ());
         let b = inner.count.access_mut(&mut ());
         core::mem::swap(a, b);
     }
Quoted 3 lines

Maybe prevent this by checking for assert!(mem::size_of::<U>() != 0); in the new function? Though I am not sure if a ZST is the only way for values to share addresses.

I'll add such an assert a part of a const inside an impl block so that we get it to fail at compile time if misused.

Quoted 6 lines

--
Cheers,
Benno

maintainer
#39 lore raw
In reply to Wedson Almeida Filho
Quoted 52 lines · On Thu, 30 Mar 2023 01:39:42 -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.

---
 rust/kernel/sync.rs | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)
rust/kernel/sync.rs +24 -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.

rust/kernel/sync.rs line 44

Quoted 10 lines
rust/kernel/sync.rs +10 -0
+#[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 generateis one based on the source code

Typo.

Quoted 11 lines
rust/kernel/sync.rs +11 -0
+/// location.
+#[doc(hidden)]
+#[macro_export]
+macro_rules! optional_name {
+    () => {
+        $crate::c_str!(core::concat!(core::file!(), ":", core::line!()))
+    };
+    ($name:literal) => {
+        $crate::c_str!($name)
+    };
+}
#40 lore raw
In reply to Wedson Almeida Filho
Quoted 14 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.

---

rust/kernel/sync.rs line 20

Quoted 3 lines
rust/kernel/sync.rs +3 -0
+// SAFETY: `bindings::lock_class_key` is designed to be used concurrently from multiple threads and
+// provides its own synchronization.
+unsafe impl Sync for LockClassKey {}

No Send?

rust/kernel/sync.rs line 31

Quoted 11 lines
rust/kernel/sync.rs +11 -0
+
+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()
+    }

I would just make this pub and drop the #[allow(dead_code)]. I think it is often useful to have methods like this available publicly.

#41 lore raw
Quoted 8 lines · Alice Ryhl
Quoted 6 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.

Quoted 13 lines

rust/kernel/sync.rs line 20

Quoted 11 lines

---

rust/kernel/sync.rs +3 -0
+// SAFETY: `bindings::lock_class_key` is designed to be used concurrently from multiple threads and
+// provides its own synchronization.
+unsafe impl Sync for LockClassKey {}

No Send?

We haven't needed it. We can add it when needed.

Quoted 6 lines
Quoted 6 lines
rust/kernel/sync.rs +6 -0
+
+impl LockClassKey {
+    /// Creates a new lock class key.
+    pub const fn new() -> Self {
+        Self(Opaque::uninit())
+    }
Quoted 8 lines

rust/kernel/sync.rs line 31

Quoted 5 lines
rust/kernel/sync.rs +5 -0
+
+    #[allow(dead_code)]
+    pub(crate) fn as_ptr(&self) -> *mut bindings::lock_class_key {
+        self.0.get()
+    }

I would just make this pub and drop the #[allow(dead_code)]. I think it is often useful to have methods like this available publicly.

The allow(dead_code) is removed on the next patch, it's here just to make this patch compile when applied alone.

This isn't public because the return type refers to a type from bindings, which we intend to eventually hide from drivers, making it public now would like our lives harder in the future.