rust: sync: introduce `LockClassKey`
Subsystems (3)
PATCH v3 1/13 rust: sync: introduce `LockClassKey`
From: Wedson Almeida Filho <[email protected]>
It is a wrapper around C's lock_class_key, which is used by the synchronisation primitives that are checked with lockdep. This is in preparation for introducing Rust abstractions for these primitives.
---
v1 -> v2: Fixed a typo in comment
v2 -> v3: Replaced core with ::core in macro
rust/kernel/sync.rs | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+)
rust/kernel/sync.rs +45 -0
@@ -5,6 +5,51 @@//! This module contains the kernel APIs related to synchronisation that have been ported or //! wrapped for usage by Rust code in the kernel. +use crate ::types::Opaque ; +mod arc;pub use arc::{Arc ,ArcBorrow ,UniqueArc }; + +/// Represents a lockdep class. It's a wrapper around C's `lock_class_key`. +#[repr(transparent)] +pub struct LockClassKey (Opaque <bindings::lock_class_key >); + +// SAFETY: `bindings::lock_class_key` is designed to be used concurrently from multiple threads and +// provides its own synchronization. +unsafe impl Sync for LockClassKey {} + +impl LockClassKey { +/// Creates a new lock class key. +pub const fn new () ->Self { +Self (Opaque ::uninit ()) + } + +#[allow(dead_code)] +pub (crate )fn as_ptr (&self) -> *mut bindings::lock_class_key { + self.0 .get () + } +} + +/// Defines a new static lock class and returns a pointer to it. +#[doc(hidden)] +#[macro_export] +macro_rules! static_lock_class { + () => {{ +static CLASS : $crate::sync::LockClassKey = $crate::sync::LockClassKey ::new (); + &CLASS + }}; +} + +/// Returns the given string, if one is provided, otherwise generates one based on the source code +/// location. +#[doc(hidden)] +#[macro_export] +macro_rules! optional_name { + () => { + $crate::c_str!(::core::concat!(::core::file!(),":" , ::core::line!())) + }; + ($name:literal) => { + $crate::c_str!($name) + }; +}
Signature · 1 line
2.34.1
PATCH v3 2/13 rust: sync: introduce `Lock` and `Guard`
From: Wedson Almeida Filho <[email protected]>
They are generic Rust implementations of a lock and a lock guard that contain code that is common to all locks. Different backends will be introduced in subsequent commits.
---
v1 -> v2: No changes
v2 -> v3: Use new Opaque::ffi_init from Benno's series
rust/kernel/sync.rs | 2 +- rust/kernel/sync/lock.rs | 162 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 163 insertions(+), 1 deletion(-) create mode 100644 rust/kernel/sync/lock.rs
rust/kernel/sync.rs +1 -1
@@ -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 +162 -0
162 lines not on this page · raw message
Signature · 1 line
2.34.1
Re: [PATCH v3 02/13] rust: sync: introduce `Lock` and `Guard`
Quoted 93 lines · Wedson Almeida Filho
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.
Suggested-by Gary Guo <[email protected]>Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: No changes
v2 -> v3: Use newOpaque::ffi_initfrom Benno's seriesrust/kernel/sync.rs | 2 +- rust/kernel/sync/lock.rs | 162 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 163 insertions(+), 1 deletion(-) create mode 100644 rust/kernel/sync/lock.rsrust/kernel/sync.rs +1
-1@@ -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 +50
-0@@ -0,0 +1,162 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Generic kernel lock and guard. +//! +//! It contains a generic Rust lock and guard that allow for different backends (e.g., mutexes, +//! spinlocks, raw spinlocks) to be provided with minimal effort. + +use super ::LockClassKey ; +use crate ::{bindings, init::PinInit , pin_init, str::CStr , types::Opaque }; +use core::{cell::UnsafeCell , marker::PhantomData , marker::PhantomPinned }; +use macros::pin_data; + +/// The "backend" of a lock. +/// +/// It is the actual implementation of the lock, without the need to repeat patterns used in all +/// locks. +/// +/// # Safety +/// +/// - 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`. +pub unsafe trait Backend { +/// The state required by the lock. +type State ; + +/// The state required to be kept between lock and unlock. +type GuardState ; + +/// Initialises the lock. +/// +/// # Safety +/// +/// `ptr` must be valid for write for the duration of the call, while `name` and `key` must +/// remain valid for read indefinitely. +unsafe fn init ( + ptr: *mut Self ::State , + name: *const core::ffi::c_char , + key: *mut bindings::lock_class_key , + ); + +/// Acquires the lock, making the caller its owner. +/// +/// # Safety +/// +/// Callers must ensure that [`Backend::init`] has been previously called. +#[must_use] +unsafe fn lock (ptr: *mut Self ::State ) ->Self ::GuardState ; + +/// Releases the lock, giving up its ownership. +///
rust/kernel/sync/lock.rs line 60
Quoted 10 lines
rust/kernel/sync/lock.rs new file +10
-0+/// # Safety +/// +/// It must only be called by the current owner of the lock. +unsafe fn unlock (ptr: *mut Self ::State , guard_state: &Self ::GuardState ); +} + +/// A mutual exclusion primitive. +/// +/// Exposes one of the kernel locking primitives. Which one is exposed depends on the lock banckend +/// specified as the generic parameter `T`.
I think this meant that it is specified by B and wraps T.
Quoted 92 lines
rust/kernel/sync/lock.rs new file +92
-0+#[pin_data] +pub struct Lock <T : ?Sized ,B :Backend > { +/// The kernel lock object. +#[pin] + state:Opaque <B ::State >, + +/// Some locks are known to be self-referential (e.g., mutexes), while others are architecture +/// or config defined (e.g., spinlocks). So we conservatively require them to be pinned in case +/// some architecture uses self-references now or in the future. +#[pin] + _pin:PhantomPinned , + +/// The data protected by the lock. + data:UnsafeCell <T >, +} + +// SAFETY: `Lock` can be transferred across thread boundaries iff the data it protects can. +unsafe impl <T : ?Sized +Send ,B :Backend >Send for Lock <T ,B > {} + +// SAFETY: `Lock` serialises the interior mutability it provides, so it is `Sync` as long as the +// data it protects is `Send`. +unsafe impl <T : ?Sized +Send ,B :Backend >Sync for Lock <T ,B > {} + +impl <T ,B :Backend >Lock <T ,B > { +/// Constructs a new lock initialiser. +#[allow(clippy::new_ret_no_self)] +pub fn new (t:T , name: &'staticCStr , key: &'staticLockClassKey ) ->impl PinInit <Self > { +pin_init! (Self { + data:UnsafeCell ::new (t), + _pin:PhantomPinned , +// SAFETY: `slot` is valid while the closure is called and both `name` and `key` have +// static lifetimes so they live indefinitely. + state <-Opaque ::ffi_init (|slot|unsafe { +B ::init (slot, name.as_char_ptr (), key.as_ptr ()) + }), + }) + } +} + +impl <T : ?Sized ,B :Backend >Lock <T ,B > { +/// Acquires the lock and gives the caller access to the data protected by it. +pub fn lock (&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 (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 +/// when a guard goes out of scope. It also provides a safe and convenient way to access the data +/// protected by the lock. +#[must_use = "the lock unlocks immediately when the guard is unused" ] +pub struct Guard <'a,T : ?Sized ,B :Backend > { +pub (crate ) lock: &'aLock <T ,B >, +pub (crate ) state:B ::GuardState , + _not_send:PhantomData <*mut ()>, +} + +// 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 > core::ops::Deref for Guard <'_,T ,B > { +type Target =T ; + +fn deref (&self) -> &Self ::Target { +// SAFETY: The caller owns the lock, so it is safe to deref the protected data. +unsafe { &*self.lock.data.get () } + } +} + +impl <T : ?Sized ,B :Backend > core::ops::DerefMut for Guard <'_,T ,B > { +fn deref_mut (&mut self) -> &mut Self ::Target { +// SAFETY: The caller owns the lock, so it is safe to deref the protected data. +unsafe { &mut *self.lock.data.get () } + } +} + +impl <T : ?Sized ,B :Backend >Drop for Guard <'_,T ,B > { +fn drop (&mut self) { +// SAFETY: The caller owns the lock, so it is safe to unlock it. +unsafe {B ::unlock (self.lock.state.get (), &self.state) }; + } +} + +impl <'a,T : ?Sized ,B :Backend >Guard <'a,T ,B > { +/// Constructs a new immutable lock guard. +/// +/// # Safety
rust/kernel/sync/lock.rs line 162
Quoted 10 lines
rust/kernel/sync/lock.rs new file +10
-0+/// +/// The caller must ensure that it owns the lock. +pub (crate )unsafe fn new (lock: &'aLock <T ,B >, state:B ::GuardState ) ->Self { +Self { + lock, + state, + _not_send:PhantomData , + } + } +}
Re: [PATCH v3 02/13] rust: sync: introduce `Lock` and `Guard`
Quoted 99 lines · Martin Rodriguez Reboredo
Quoted 97 lines · Wedson Almeida Filho
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.
Suggested-by Gary Guo <[email protected]>Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: No changes
v2 -> v3: Use newOpaque::ffi_initfrom Benno's seriesrust/kernel/sync.rs | 2 +- rust/kernel/sync/lock.rs | 162 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 163 insertions(+), 1 deletion(-) create mode 100644 rust/kernel/sync/lock.rsrust/kernel/sync.rs +1
-1@@ -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 +54
-0@@ -0,0 +1,162 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Generic kernel lock and guard. +//! +//! It contains a generic Rust lock and guard that allow for different backends (e.g., mutexes, +//! spinlocks, raw spinlocks) to be provided with minimal effort. + +use super ::LockClassKey ; +use crate ::{bindings, init::PinInit , pin_init, str::CStr , types::Opaque }; +use core::{cell::UnsafeCell , marker::PhantomData , marker::PhantomPinned }; +use macros::pin_data; + +/// The "backend" of a lock. +/// +/// It is the actual implementation of the lock, without the need to repeat patterns used in all +/// locks. +/// +/// # Safety +/// +/// - 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`. +pub unsafe trait Backend { +/// The state required by the lock. +type State ; + +/// The state required to be kept between lock and unlock. +type GuardState ; + +/// Initialises the lock. +/// +/// # Safety +/// +/// `ptr` must be valid for write for the duration of the call, while `name` and `key` must +/// remain valid for read indefinitely. +unsafe fn init ( + ptr: *mut Self ::State , + name: *const core::ffi::c_char , + key: *mut bindings::lock_class_key , + ); + +/// Acquires the lock, making the caller its owner. +/// +/// # Safety +/// +/// Callers must ensure that [`Backend::init`] has been previously called. +#[must_use] +unsafe fn lock (ptr: *mut Self ::State ) ->Self ::GuardState ; + +/// Releases the lock, giving up its ownership. +/// +/// # Safety +/// +/// It must only be called by the current owner of the lock. +unsafe fn unlock (ptr: *mut Self ::State , guard_state: &Self ::GuardState );
Quoted 8 lines
rust/kernel/sync/lock.rs line 60
Quoted 6 lines
rust/kernel/sync/lock.rs new file +6
-0+} + +/// A mutual exclusion primitive. +/// +/// Exposes one of the kernel locking primitives. Which one is exposed depends on the lock banckend +/// specified as the generic parameter `T`. I think this meant that it is specified by
Band wrapsT.
Yes, I meant B here. Will fix.
Quoted 104 lines
Quoted 92 lines
rust/kernel/sync/lock.rs new file +92
-0+#[pin_data] +pub struct Lock <T : ?Sized ,B :Backend > { +/// The kernel lock object. +#[pin] + state:Opaque <B ::State >, + +/// Some locks are known to be self-referential (e.g., mutexes), while others are architecture +/// or config defined (e.g., spinlocks). So we conservatively require them to be pinned in case +/// some architecture uses self-references now or in the future. +#[pin] + _pin:PhantomPinned , + +/// The data protected by the lock. + data:UnsafeCell <T >, +} + +// SAFETY: `Lock` can be transferred across thread boundaries iff the data it protects can. +unsafe impl <T : ?Sized +Send ,B :Backend >Send for Lock <T ,B > {} + +// SAFETY: `Lock` serialises the interior mutability it provides, so it is `Sync` as long as the +// data it protects is `Send`. +unsafe impl <T : ?Sized +Send ,B :Backend >Sync for Lock <T ,B > {} + +impl <T ,B :Backend >Lock <T ,B > { +/// Constructs a new lock initialiser. +#[allow(clippy::new_ret_no_self)] +pub fn new (t:T , name: &'staticCStr , key: &'staticLockClassKey ) ->impl PinInit <Self > { +pin_init! (Self { + data:UnsafeCell ::new (t), + _pin:PhantomPinned , +// SAFETY: `slot` is valid while the closure is called and both `name` and `key` have +// static lifetimes so they live indefinitely. + state <-Opaque ::ffi_init (|slot|unsafe { +B ::init (slot, name.as_char_ptr (), key.as_ptr ()) + }), + }) + } +} + +impl <T : ?Sized ,B :Backend >Lock <T ,B > { +/// Acquires the lock and gives the caller access to the data protected by it. +pub fn lock (&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 (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 +/// when a guard goes out of scope. It also provides a safe and convenient way to access the data +/// protected by the lock. +#[must_use = "the lock unlocks immediately when the guard is unused" ] +pub struct Guard <'a,T : ?Sized ,B :Backend > { +pub (crate ) lock: &'aLock <T ,B >, +pub (crate ) state:B ::GuardState , + _not_send:PhantomData <*mut ()>, +} + +// 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 > core::ops::Deref for Guard <'_,T ,B > { +type Target =T ; + +fn deref (&self) -> &Self ::Target { +// SAFETY: The caller owns the lock, so it is safe to deref the protected data. +unsafe { &*self.lock.data.get () } + } +} + +impl <T : ?Sized ,B :Backend > core::ops::DerefMut for Guard <'_,T ,B > { +fn deref_mut (&mut self) -> &mut Self ::Target { +// SAFETY: The caller owns the lock, so it is safe to deref the protected data. +unsafe { &mut *self.lock.data.get () } + } +} + +impl <T : ?Sized ,B :Backend >Drop for Guard <'_,T ,B > { +fn drop (&mut self) { +// SAFETY: The caller owns the lock, so it is safe to unlock it. +unsafe {B ::unlock (self.lock.state.get (), &self.state) }; + } +} + +impl <'a,T : ?Sized ,B :Backend >Guard <'a,T ,B > { +/// Constructs a new immutable lock guard. +/// +/// # Safety rust/kernel/sync/lock.rs line 162
Quoted 10 lines
rust/kernel/sync/lock.rs new file +10
-0+/// +/// The caller must ensure that it owns the lock. +pub (crate )unsafe fn new (lock: &'aLock <T ,B >, state:B ::GuardState ) ->Self { +Self { + lock, + state, + _not_send:PhantomData , + } + } +}Reviewed-by Martin Rodriguez Reboredo <[email protected]>
PATCH v3 3/13 rust: lock: introduce `Mutex`
In reply to Wedson Almeida FilhoFrom: Wedson Almeida Filho <[email protected]>
This is the struct mutex lock backend and allows Rust code to use the kernel mutex idiomatically.
---
v1 -> v2: No changes
v2 -> v3: No changes
rust/helpers.c | 7 ++ rust/kernel/sync.rs | 1 + rust/kernel/sync/lock.rs | 2 + rust/kernel/sync/lock/mutex.rs | 118 +++++++++++++++++++++++++++++++++ 4 files changed, 128 insertions(+) create mode 100644 rust/kernel/sync/lock/mutex.rs
rust/helpers.c +7 -0
@@ -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
@@ -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
@@ -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
Re: [PATCH v3 03/13] rust: lock: introduce `Mutex`
Quoted 185 lines · Wedson Almeida Filho
From: Wedson Almeida Filho <[email protected]>
This is the
struct mutexlock 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]>Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: No changes
v2 -> v3: No changesrust/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.rsrust/helpers.c +7
-0@@ -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@@ -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@@ -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 +108
-0@@ -0,0 +1,118 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! A kernel mutex. +//! +//! This module allows Rust code to use the kernel's `struct mutex`. + +use crate ::bindings; + +/// Creates a [`Mutex`] initialiser with the given name and a newly-created lock class. +/// +/// It uses the name if one is given, otherwise it generates one based on the file name and line +/// number. +#[macro_export] +macro_rules! new_mutex { + ($inner:expr $(, $name:literal)? $(,)?) => { + $crate::sync::Mutex ::new ( + $inner, $crate::optional_name!($($name)?), $crate::static_lock_class!()) + }; +} + +/// A mutual exclusion primitive. +/// +/// Exposes the kernel's [`struct mutex`]. When multiple threads attempt to lock the same mutex, +/// only one at a time is allowed to progress, the others will block (sleep) until the mutex is +/// unlocked, at which point another thread will be allowed to wake up and make progress. +/// +/// Since it may block, [`Mutex`] needs to be used with care in atomic contexts. +/// +/// Instances of [`Mutex`] need a lock class and to be pinned. The recommended way to create such +/// instances is with the [`pin_init`](crate::pin_init) and [`new_mutex`] macros. +/// +/// # Examples +/// +/// The following example shows how to declare, allocate and initialise a struct (`Example`) that +/// contains an inner struct (`Inner`) that is protected by a mutex. +/// +/// ``` +/// use kernel::{init::InPlaceInit, init::PinInit, new_mutex, pin_init, sync::Mutex}; +/// +/// struct Inner { +/// a: u32, +/// b: u32, +/// } +/// +/// #[pin_data] +/// struct Example { +/// c: u32, +/// #[pin] +/// d: Mutex<Inner>, +/// } +/// +/// impl Example { +/// fn new() -> impl PinInit<Self> { +/// pin_init!(Self { +/// c: 10, +/// d <- new_mutex!(Inner { a: 20, b: 30 }), +/// }) +/// } +/// } +/// +/// // Allocate a boxed `Example`. +/// let e = Box::pin_init(Example::new())?; +/// assert_eq!(e.c, 10); +/// assert_eq!(e.d.lock().a, 20); +/// assert_eq!(e.d.lock().b, 30); +/// ``` +/// +/// The following example shows how to use interior mutability to modify the contents of a struct +/// protected by a mutex despite only having a shared reference: +/// +/// ``` +/// use kernel::sync::Mutex; +/// +/// struct Example { +/// a: u32, +/// b: u32, +/// } +/// +/// fn example(m: &Mutex<Example>) { +/// let mut guard = m.lock(); +/// guard.a += 10; +/// guard.b += 20; +/// } +/// ``` +/// +/// [`struct mutex`]: ../../../../include/linux/mutex.h +pub type Mutex <T > =super ::Lock <T ,MutexBackend >; + +/// A kernel `struct mutex` lock backend. +pub struct MutexBackend ; + +// SAFETY: The underlying kernel `struct mutex` object ensures mutual exclusion. +unsafe impl super ::Backend for MutexBackend { +type State = bindings::mutex ; +type GuardState = (); + +unsafe fn init ( + ptr: *mut Self ::State , + name: *const core::ffi::c_char , + key: *mut bindings::lock_class_key , + ) { +// SAFETY: The safety requirements ensure that `ptr` is valid for writes, and `name` and +// `key` are valid for read indefinitely. +unsafe { bindings::__mutex_init (ptr, name, key) } + } + +unsafe fn lock (ptr: *mut Self ::State ) ->Self ::GuardState { +// SAFETY: The safety requirements of this function ensure that `ptr` points to valid
rust/kernel/sync/lock/mutex.rs line 118
Quoted 10 lines
rust/kernel/sync/lock/mutex.rs new file +10
-0+// memory, and that it has been initialised before. +unsafe { bindings::mutex_lock (ptr) }; + } + +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::mutex_unlock (ptr) }; + } +}
PATCH v3 4/13 locking/spinlock: introduce spin_lock_init_with_key
In reply to Wedson Almeida FilhoFrom: 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.
---
v1 -> v2: No changes
v2 -> v3: No changes
include/linux/spinlock.h | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-)
include/linux/spinlock.h +7 -2
@@ -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
Re: [PATCH v3 04/13] locking/spinlock: introduce spin_lock_init_with_key
Quoted 32 lines · 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]>Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: No changes
v2 -> v3: No changesinclude/linux/spinlock.h | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-)include/linux/spinlock.h +6
-0@@ -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 ); +} +
include/linux/spinlock.h static __always_inline raw_spinlock_t *spinlock_check(spinlock_t *lock) · line 343
Quoted 10 lines
include/linux/spinlock.h +1
-2# 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
PATCH v3 5/13 rust: lock: introduce `SpinLock`
In reply to Wedson Almeida FilhoFrom: Wedson Almeida Filho <[email protected]>
This is the spinlock_t lock backend and allows Rust code to use the kernel spinlock idiomatically.
---
v1 -> v2: No changes
v2 -> v3: No changes
rust/helpers.c | 24 +++++++ rust/kernel/sync.rs | 2 +- rust/kernel/sync/lock.rs | 1 + rust/kernel/sync/lock/spinlock.rs | 116 ++++++++++++++++++++++++++++++ 4 files changed, 142 insertions(+), 1 deletion(-) create mode 100644 rust/kernel/sync/lock/spinlock.rs
rust/helpers.c +24 -0
@@ -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
@@ -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
@@ -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
Re: [PATCH v3 05/13] rust: lock: introduce `SpinLock`
Quoted 200 lines · Wedson Almeida Filho
From: Wedson Almeida Filho <[email protected]>
This is the
spinlock_tlock 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]>Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: No changes
v2 -> v3: No changesrust/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.rsrust/helpers.c +24
-0@@ -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@@ -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@@ -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 +106
-0@@ -0,0 +1,116 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! A kernel spinlock. +//! +//! This module allows Rust code to use the kernel's `spinlock_t`. + +use crate ::bindings; + +/// Creates a [`SpinLock`] initialiser with the given name and a newly-created lock class. +/// +/// It uses the name if one is given, otherwise it generates one based on the file name and line +/// number. +#[macro_export] +macro_rules! new_spinlock { + ($inner:expr $(, $name:literal)? $(,)?) => { + $crate::sync::SpinLock ::new ( + $inner, $crate::optional_name!($($name)?), $crate::static_lock_class!()) + }; +} + +/// A spinlock. +/// +/// Exposes the kernel's [`spinlock_t`]. When multiple CPUs attempt to lock the same spinlock, only +/// one at a time is allowed to progress, the others will block (spinning) until the spinlock is +/// unlocked, at which point another CPU will be allowed to make progress. +/// +/// Instances of [`SpinLock`] need a lock class and to be pinned. The recommended way to create such +/// instances is with the [`pin_init`](crate::pin_init) and [`new_spinlock`] macros. +/// +/// # Examples +/// +/// The following example shows how to declare, allocate and initialise a struct (`Example`) that +/// contains an inner struct (`Inner`) that is protected by a spinlock. +/// +/// ``` +/// use kernel::{init::InPlaceInit, init::PinInit, new_spinlock, pin_init, sync::SpinLock}; +/// +/// struct Inner { +/// a: u32, +/// b: u32, +/// } +/// +/// #[pin_data] +/// struct Example { +/// c: u32, +/// #[pin] +/// d: SpinLock<Inner>, +/// } +/// +/// impl Example { +/// fn new() -> impl PinInit<Self> { +/// pin_init!(Self { +/// c: 10, +/// d <- new_spinlock!(Inner { a: 20, b: 30 }), +/// }) +/// } +/// } +/// +/// // Allocate a boxed `Example`. +/// let e = Box::pin_init(Example::new())?; +/// assert_eq!(e.c, 10); +/// assert_eq!(e.d.lock().a, 20); +/// assert_eq!(e.d.lock().b, 30); +/// ``` +/// +/// The following example shows how to use interior mutability to modify the contents of a struct +/// protected by a spinlock despite only having a shared reference: +/// +/// ``` +/// use kernel::sync::SpinLock; +/// +/// struct Example { +/// a: u32, +/// b: u32, +/// } +/// +/// fn example(m: &SpinLock<Example>) { +/// let mut guard = m.lock(); +/// guard.a += 10; +/// guard.b += 20; +/// } +/// ``` +/// +/// [`spinlock_t`]: ../../../../include/linux/spinlock.h +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. +unsafe impl super ::Backend for SpinLockBackend { +type State = bindings::spinlock_t ; +type GuardState = (); + +unsafe fn init ( + ptr: *mut Self ::State , + name: *const core::ffi::c_char , + key: *mut bindings::lock_class_key , + ) { +// SAFETY: The safety requirements ensure that `ptr` is valid for writes, and `name` and +// `key` are valid for read indefinitely. +unsafe { bindings::__spin_lock_init (ptr, name, key) } + } + +unsafe fn lock (ptr: *mut Self ::State ) ->Self ::GuardState { +// SAFETY: The safety requirements of this function ensure that `ptr` points to valid
rust/kernel/sync/lock/spinlock.rs line 116
Quoted 10 lines
rust/kernel/sync/lock/spinlock.rs new file +10
-0+// memory, and that it has been initialised before. +unsafe { bindings::spin_lock (ptr) } + } + +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) } + } +}
PATCH v3 6/13 rust: lock: add support for `Lock::lock_irqsave`
In reply to Wedson Almeida FilhoFrom: Wedson Almeida Filho <[email protected]>
This allows locks like spinlocks and raw spinlocks to expose a lock_irqsave variant in Rust that corresponds to the C version.
---
v1 -> v2: No changes
v2 -> v3: No changes
rust/kernel/sync/lock.rs | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+)
rust/kernel/sync/lock.rs +38 -0
@@ -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
@@ -111,6 +134,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
Re: [PATCH v3 06/13] rust: lock: add support for `Lock::lock_irqsave`
Quoted 59 lines · Wedson Almeida Filho
From: Wedson Almeida Filho <[email protected]>
This allows locks like spinlocks and raw spinlocks to expose a
lock_irqsavevariant in Rust that corresponds to the C version.Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: No changes
v2 -> v3: No changesrust/kernel/sync/lock.rs | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+)rust/kernel/sync/lock.rs +31
-0@@ -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 @@ -111,6 +134,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
rust/kernel/sync/lock.rs impl<T: ?Sized, B: Backend> Lock<T, B> { · line 154
Quoted 10 lines
rust/kernel/sync/lock.rs +7
-0+// 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
PATCH v3 7/13 rust: lock: implement `IrqSaveBackend` for `SpinLock`
In reply to Wedson Almeida FilhoFrom: Wedson Almeida Filho <[email protected]>
This allows Rust code to use the lock_irqsave variant of spinlocks.
---
v1 -> v2: No changes
v2 -> v3: No changes
rust/helpers.c | 16 +++++++++++++ rust/kernel/sync/lock/spinlock.rs | 38 ++++++++++++++++++++++++++----- 2 files changed, 48 insertions(+), 6 deletions(-)
rust/helpers.c +16 -0
@@ -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
@@ -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
Re: [PATCH v3 07/13] rust: lock: implement `IrqSaveBackend` for `SpinLock`
Quoted 105 lines · Wedson Almeida Filho
From: Wedson Almeida Filho <[email protected]>
This allows Rust code to use the
lock_irqsavevariant of spinlocks.Cc Peter Zijlstra <[email protected]>Cc Ingo Molnar <[email protected]>Cc Will Deacon <[email protected]>Cc Waiman Long <[email protected]>Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: No changes
v2 -> v3: No changesrust/helpers.c | 16 +++++++++++++ rust/kernel/sync/lock/spinlock.rs | 38 ++++++++++++++++++++++++++----- 2 files changed, 48 insertions(+), 6 deletions(-)rust/helpers.c +16
-0@@ -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 +24
-6@@ -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`
rust/kernel/sync/lock/spinlock.rs unsafe impl super::Backend for SpinLockBackend { · line 142
Quoted 10 lines
rust/kernel/sync/lock/spinlock.rs +8
-0+// 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) }) } }
PATCH v3 8/13 rust: introduce `ARef`
In reply to Wedson Almeida FilhoFrom: Wedson Almeida Filho <[email protected]>
This is an owned reference to an object that is always ref-counted. This is meant to be used in wrappers for C types that have their own ref counting functions, for example, tasks, files, inodes, dentries, etc.
---
v1 -> v2: No changes
v2 -> v3: No changes
rust/kernel/types.rs | 107 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+)
rust/kernel/types.rs +107 -0
@@ -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.
@@ -268,6 +270,111 @@ impl<T> Opaque<T> { } } +/// 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
Re: [PATCH v3 08/13] rust: introduce `ARef`
Quoted 131 lines · Wedson Almeida Filho
From: Wedson Almeida Filho <[email protected]>
This is an owned reference to an object that is always ref-counted. This is meant to be used in wrappers for C types that have their own ref counting functions, for example, tasks, files, inodes, dentries, etc.
Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: No changes
v2 -> v3: No changesrust/kernel/types.rs | 107 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+)rust/kernel/types.rs +100
-0@@ -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. @@ -268,6 +270,111 @@ impl<T> Opaque<T> { } } +/// 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 > {
rust/kernel/types.rs impl<T> Opaque<T> { · line 380
Quoted 10 lines
rust/kernel/types.rs +7
-0+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`.
PATCH v3 9/13 rust: add basic `Task`
In reply to Wedson Almeida FilhoFrom: Wedson Almeida Filho <[email protected]>
It is an abstraction for C's struct task_struct. It implements AlwaysRefCounted, so the refcount of the wrapped object is managed safely on the Rust side.
---
v1 -> v2: No changes
v2 -> v3: Wrap task_struct with Opaque instead of UnsafeCell
rust/bindings/bindings_helper.h | 1 + rust/helpers.c | 19 +++++++++ rust/kernel/lib.rs | 1 + rust/kernel/task.rs | 75 +++++++++++++++++++++++++++++++++ 4 files changed, 96 insertions(+) create mode 100644 rust/kernel/task.rs
rust/bindings/bindings_helper.h +1 -0
@@ -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
@@ -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
@@ -44,6 +44,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 +75 -0
75 lines not on this page · raw message
Signature · 1 line
2.34.1
Re: [PATCH v3 09/13] rust: add basic `Task`
Quoted 159 lines · Wedson Almeida Filho
From: Wedson Almeida Filho <[email protected]>
It is an abstraction for C's
struct task_struct. It implementsAlwaysRefCounted, so the refcount of the wrapped object is managed safely on the Rust side.Cc Ingo Molnar <[email protected]>Cc Peter Zijlstra <[email protected]>Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: No changes
v2 -> v3: Wraptask_structwithOpaqueinstead ofUnsafeCellrust/bindings/bindings_helper.h | 1 + rust/helpers.c | 19 +++++++++ rust/kernel/lib.rs | 1 + rust/kernel/task.rs | 75 +++++++++++++++++++++++++++++++++ 4 files changed, 96 insertions(+) create mode 100644 rust/kernel/task.rsrust/bindings/bindings_helper.h +1
-0@@ -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@@ -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@@ -44,6 +44,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 +65
-0@@ -0,0 +1,75 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! Tasks (threads and processes). +//! +//! C header: [`include/linux/sched.h`](../../../../include/linux/sched.h). + +use crate ::{bindings, types::Opaque }; +use core::ptr; + +/// Wraps the kernel's `struct task_struct`. +/// +/// # Invariants +/// +/// All instances are valid tasks created by the C portion of the kernel. +/// +/// 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`. +#[repr(transparent)] +pub struct Task (pub (crate )Opaque <bindings::task_struct >); + +// SAFETY: It's OK to access `Task` through references from other threads because we're either +// accessing properties that don't change (e.g., `pid`, `group_leader`) or that are properly +// synchronised by C code (e.g., `signal_pending`). +unsafe impl Sync for Task {} + +/// The type of process identifiers (PIDs). +type Pid = bindings::pid_t ; + +impl Task { +/// Returns the group leader of the given task. +pub fn group_leader (&self) -> &Task { +// SAFETY: By the type invariant, we know that `self.0` is a valid task. Valid tasks always +// have a valid group_leader. +let ptr =unsafe { *ptr::addr_of!((*self.0 .get ()).group_leader) }; + +// SAFETY: The lifetime of the returned task reference is tied to the lifetime of `self`, +// and given that a task has a reference to its group leader, we know it must be valid for +// the lifetime of the returned task reference. +unsafe { &*ptr.cast () } + } + +/// Returns the PID of the given task. +pub fn pid (&self) ->Pid { +// SAFETY: By the type invariant, we know that `self.0` is a valid task. Valid tasks always +// have a valid pid. +unsafe { *ptr::addr_of!((*self.0 .get ()).pid) } + } + +/// Determines whether the given task has pending signals. +pub fn signal_pending (&self) ->bool { +// SAFETY: By the type invariant, we know that `self.0` is valid. +unsafe { bindings::signal_pending (self.0 .get ()) !=0 } + } + +/// Wakes up the task. +pub fn wake_up (&self) { +// SAFETY: By the type invariant, we know that `self.0.get()` is non-null and valid. +// And `wake_up_process` is safe to be called for any valid task, even if the task is +// running. +unsafe { bindings::wake_up_process (self.0 .get ()) }; + } +} + +// SAFETY: The type invariants guarantee that `Task` is always ref-counted. +unsafe impl crate ::types::AlwaysRefCounted for Task {
rust/kernel/task.rs line 75
Quoted 10 lines
rust/kernel/task.rs new file +10
-0+fn inc_ref (&self) { +// SAFETY: The existence of a shared reference means that the refcount is nonzero. +unsafe { bindings::get_task_struct (self.0 .get ()) }; + } + +unsafe fn dec_ref (obj: ptr::NonNull <Self >) { +// SAFETY: The safety requirements guarantee that the refcount is nonzero. +unsafe { bindings::put_task_struct (obj.cast ().as_ptr ()) } + } +}
PATCH v3 10/13 rust: introduce `current`
In reply to Wedson Almeida FilhoFrom: Wedson Almeida Filho <[email protected]>
This allows Rust code to get a reference to the current task without having to increment the refcount, but still guaranteeing memory safety.
---
v1 -> v2: Make current a macro to prevent it from escaping the caller v2 -> v3:
- Mention current macro in Task::current
- Hide implementation of TaskRef inside Task::current
rust/helpers.c | 6 +++ rust/kernel/prelude.rs | 2 + rust/kernel/task.rs | 88 +++++++++++++++++++++++++++++++++++++++++- 3 files changed, 95 insertions(+), 1 deletion(-)
rust/helpers.c +6 -0
@@ -100,6 +100,12 @@ bool rust_helper_refcount_dec_and_test(refcount_t *r) }EXPORT_SYMBOL_GPL (rust_helper_refcount_dec_and_test); +struct task_struct *rust_helper_get_current (void ) +{ +return current; +} +EXPORT_SYMBOL_GPL (rust_helper_get_current); +void rust_helper_get_task_struct (struct task_struct *t) {get_task_struct (t);
rust/kernel/prelude.rs +2 -0
@@ -36,3 +36,5 @@ pub use super::error::{code::*, Error, Result};pub use super ::{str::CStr ,ThisModule };pub use super ::init::{InPlaceInit ,Init ,PinInit }; + +pub use super ::current;
rust/kernel/task.rs +87 -1
106 lines not on this page · raw message
Signature · 1 line
2.34.1
Re: [PATCH v3 10/13] rust: introduce `current`
Quoted 119 lines · Wedson Almeida Filho
From: Wedson Almeida Filho <[email protected]>
This allows Rust code to get a reference to the current task without having to increment the refcount, but still guaranteeing memory safety.
Cc Ingo Molnar <[email protected]>Cc Peter Zijlstra <[email protected]>Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: Makecurrenta macro to prevent it from escaping the caller v2 -> v3:
- Mentioncurrentmacro inTask::current
- Hide implementation ofTaskRefinsideTask::currentrust/helpers.c | 6 +++ rust/kernel/prelude.rs | 2 + rust/kernel/task.rs | 88 +++++++++++++++++++++++++++++++++++++++++- 3 files changed, 95 insertions(+), 1 deletion(-)rust/helpers.c +6
-0@@ -100,6 +100,12 @@ bool rust_helper_refcount_dec_and_test(refcount_t *r) }EXPORT_SYMBOL_GPL (rust_helper_refcount_dec_and_test); +struct task_struct *rust_helper_get_current (void ) +{ +return current; +} +EXPORT_SYMBOL_GPL (rust_helper_get_current); +void rust_helper_get_task_struct (struct task_struct *t) {get_task_struct (t);rust/kernel/prelude.rs +2
-0@@ -36,3 +36,5 @@ pub use super::error::{code::*, Error, Result};pub use super ::{str::CStr ,ThisModule };pub use super ::init::{InPlaceInit ,Init ,PinInit }; + +pub use super ::current;rust/kernel/task.rs +50
-1@@ -5,7 +5,17 @@//! C header: [`include/linux/sched.h`](../../../../include/linux/sched.h). use crate ::{bindings, types::Opaque }; -use core::ptr; +use core::{marker::PhantomData , ops::Deref , ptr}; + +/// Returns the currently running task. +#[macro_export] +macro_rules! current { + () => { +// SAFETY: Deref + addr-of below create a temporary `TaskRef` that cannot outlive the +// caller. +unsafe { &*$crate::task::Task ::current () } + }; +}/// Wraps the kernel's `struct task_struct`. /// @@ -15,6 +25,42 @@ use core::ptr;/// /// Instances of this type are always ref-counted, that is, a call to `get_task_struct` ensures /// that the allocation remains valid at least until the matching call to `put_task_struct`. +/// +/// # Examples +/// +/// The following is an example of getting the PID of the current thread with zero additional cost +/// when compared to the C version: +/// +/// ``` +/// let pid = current!().pid(); +/// ``` +/// +/// Getting the PID of the current process, also zero additional cost: +/// +/// ``` +/// let pid = current!().group_leader().pid(); +/// ``` +/// +/// Getting the current task and storing it in some struct. The reference count is automatically +/// incremented when creating `State` and decremented when it is dropped: +/// +/// ``` +/// use kernel::{task::Task, types::ARef}; +/// +/// struct State { +/// creator: ARef<Task>, +/// index: u32, +/// } +/// +/// impl State { +/// fn new() -> Self { +/// Self { +/// creator: current!().into(), +/// index: 0, +/// } +/// } +/// } +/// ``` #[repr(transparent)] pub struct Task (pub (crate )Opaque <bindings::task_struct >);@@ -27,6 +73,46 @@ unsafe impl Sync for Task {}type Pid = bindings::pid_t ;impl Task { +/// Returns a task reference for the currently executing task/thread. +/// +/// The recommended way to get the current task/thread is to use the
rust/kernel/task.rs unsafe impl Sync for Task {} · line 88
Quoted 10 lines
rust/kernel/task.rs +10
-0+/// [`current`](crate::current) macro because it is safe. +/// +/// # Safety +/// +/// Callers must ensure that the returned object doesn't outlive the current task/thread. +pub unsafe fn current () ->impl Deref <Target =Task > { +pub struct TaskRef <'a> { + task: &'aTask , + _not_send:PhantomData <*mut ()>, + }
I'd had named this as CurrentTaskRef, but since this is not exposed to users then there are no problems whatsoever.
Quoted 20 lines
rust/kernel/task.rs +20
-0+ +impl Deref for TaskRef <'_> { +type Target =Task ; + +fn deref (&self) -> &Self ::Target { + self.task + } + } + +impl From <TaskRef <'_>>for crate ::types::ARef <Task > { +fn from (t:TaskRef <'_>) ->Self { + t.deref ().into () + } + } + +// SAFETY: Just an FFI call with no additional safety requirements. +let ptr =unsafe { bindings::get_current () }; + +TaskRef { +// SAFETY: If the current thread is still running, the current task is valid. Given
rust/kernel/task.rs unsafe impl Sync for Task {} · line 118
Quoted 10 lines
rust/kernel/task.rs +7
-0+// that `TaskRef` is not `Send`, we know it cannot be transferred to another thread +// (where it could potentially outlive the caller). + task: unsafe { &*ptr.cast() }, + _not_send: PhantomData, + } + } +/// Returns the group leader of the given task. pub fn group_leader (&self) -> &Task {// SAFETY: By the type invariant, we know that `self.0` is a valid task. Valid tasks always
Re: [PATCH v3 10/13] rust: introduce `current`
In reply to Wedson Almeida FilhoQuoted 133 lines · Wedson Almeida Filho
From: Wedson Almeida Filho <[email protected]>
This allows Rust code to get a reference to the current task without having to increment the refcount, but still guaranteeing memory safety.
Cc Ingo Molnar <[email protected]>Cc Peter Zijlstra <[email protected]>Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: Makecurrenta macro to prevent it from escaping the caller v2 -> v3:
- Mentioncurrentmacro inTask::current
- Hide implementation ofTaskRefinsideTask::currentrust/helpers.c | 6 +++ rust/kernel/prelude.rs | 2 + rust/kernel/task.rs | 88 +++++++++++++++++++++++++++++++++++++++++- 3 files changed, 95 insertions(+), 1 deletion(-)rust/helpers.c +6
-0@@ -100,6 +100,12 @@ bool rust_helper_refcount_dec_and_test(refcount_t *r) }EXPORT_SYMBOL_GPL (rust_helper_refcount_dec_and_test); +struct task_struct *rust_helper_get_current (void ) +{ +return current; +} +EXPORT_SYMBOL_GPL (rust_helper_get_current); +void rust_helper_get_task_struct (struct task_struct *t) {get_task_struct (t);rust/kernel/prelude.rs +2
-0@@ -36,3 +36,5 @@ pub use super::error::{code::*, Error, Result};pub use super ::{str::CStr ,ThisModule };pub use super ::init::{InPlaceInit ,Init ,PinInit }; + +pub use super ::current;rust/kernel/task.rs +64
-1@@ -5,7 +5,17 @@//! C header: [`include/linux/sched.h`](../../../../include/linux/sched.h). use crate ::{bindings, types::Opaque }; -use core::ptr; +use core::{marker::PhantomData , ops::Deref , ptr}; + +/// Returns the currently running task. +#[macro_export] +macro_rules! current { + () => { +// SAFETY: Deref + addr-of below create a temporary `TaskRef` that cannot outlive the +// caller. +unsafe { &*$crate::task::Task ::current () } + }; +}/// Wraps the kernel's `struct task_struct`. /// @@ -15,6 +25,42 @@ use core::ptr;/// /// Instances of this type are always ref-counted, that is, a call to `get_task_struct` ensures /// that the allocation remains valid at least until the matching call to `put_task_struct`. +/// +/// # Examples +/// +/// The following is an example of getting the PID of the current thread with zero additional cost +/// when compared to the C version: +/// +/// ``` +/// let pid = current!().pid(); +/// ``` +/// +/// Getting the PID of the current process, also zero additional cost: +/// +/// ``` +/// let pid = current!().group_leader().pid(); +/// ``` +/// +/// Getting the current task and storing it in some struct. The reference count is automatically +/// incremented when creating `State` and decremented when it is dropped: +/// +/// ``` +/// use kernel::{task::Task, types::ARef}; +/// +/// struct State { +/// creator: ARef<Task>, +/// index: u32, +/// } +/// +/// impl State { +/// fn new() -> Self { +/// Self { +/// creator: current!().into(), +/// index: 0, +/// } +/// } +/// } +/// ``` #[repr(transparent)] pub struct Task (pub (crate )Opaque <bindings::task_struct >);@@ -27,6 +73,46 @@ unsafe impl Sync for Task {}type Pid = bindings::pid_t ;impl Task { +/// Returns a task reference for the currently executing task/thread. +/// +/// The recommended way to get the current task/thread is to use the +/// [`current`](crate::current) macro because it is safe. +/// +/// # Safety +/// +/// Callers must ensure that the returned object doesn't outlive the current task/thread. +pub unsafe fn current () ->impl Deref <Target =Task > { +pub struct TaskRef <'a> { + task: &'aTask , + _not_send:PhantomData <*mut ()>, + } + +impl Deref for TaskRef <'_> { +type Target =Task ; +
rust/kernel/task.rs unsafe impl Sync for Task {} · line 102
Quoted 10 lines
rust/kernel/task.rs +10
-0+fn deref (&self) -> &Self ::Target { + self.task + } + } + +impl From <TaskRef <'_>>for crate ::types::ARef <Task > { +fn from (t:TaskRef <'_>) ->Self { + t.deref ().into () + } + }
I think we can remove this From impl, since the type is never exposed to the outside (there still is the From<&T> for ARef<T> impl, so users can still do current!().into() to get an ARef<Task>).
--
Cheers,
Benno
Quoted 19 lines
rust/kernel/task.rs +13
-1+ +// SAFETY: Just an FFI call with no additional safety requirements. +let ptr =unsafe { bindings::get_current () }; + +TaskRef { +// SAFETY: If the current thread is still running, the current task is valid. Given +// that `TaskRef` is not `Send`, we know it cannot be transferred to another thread +// (where it could potentially outlive the caller). + task:unsafe { &*ptr.cast () }, + _not_send:PhantomData , + } + } +/// Returns the group leader of the given task. pub fn group_leader (&self) -> &Task {// SAFETY: By the type invariant, we know that `self.0` is a valid task. Valid tasks always --2.34.1
Re: [PATCH v3 10/13] rust: introduce `current`
Quoted 141 lines · Benno Lossin
Quoted 139 lines · Wedson Almeida Filho
From: Wedson Almeida Filho <[email protected]>
This allows Rust code to get a reference to the current task without having to increment the refcount, but still guaranteeing memory safety.
Cc Ingo Molnar <[email protected]>Cc Peter Zijlstra <[email protected]>Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: Makecurrenta macro to prevent it from escaping the caller v2 -> v3:
- Mentioncurrentmacro inTask::current
- Hide implementation ofTaskRefinsideTask::currentrust/helpers.c | 6 +++ rust/kernel/prelude.rs | 2 + rust/kernel/task.rs | 88 +++++++++++++++++++++++++++++++++++++++++- 3 files changed, 95 insertions(+), 1 deletion(-)rust/helpers.c +6
-0@@ -100,6 +100,12 @@ bool rust_helper_refcount_dec_and_test(refcount_t *r) }EXPORT_SYMBOL_GPL (rust_helper_refcount_dec_and_test); +struct task_struct *rust_helper_get_current (void ) +{ +return current; +} +EXPORT_SYMBOL_GPL (rust_helper_get_current); +void rust_helper_get_task_struct (struct task_struct *t) {get_task_struct (t);rust/kernel/prelude.rs +2
-0@@ -36,3 +36,5 @@ pub use super::error::{code::*, Error, Result};pub use super ::{str::CStr ,ThisModule };pub use super ::init::{InPlaceInit ,Init ,PinInit }; + +pub use super ::current;rust/kernel/task.rs +70
-1@@ -5,7 +5,17 @@//! C header: [`include/linux/sched.h`](../../../../include/linux/sched.h). use crate ::{bindings, types::Opaque }; -use core::ptr; +use core::{marker::PhantomData , ops::Deref , ptr}; + +/// Returns the currently running task. +#[macro_export] +macro_rules! current { + () => { +// SAFETY: Deref + addr-of below create a temporary `TaskRef` that cannot outlive the +// caller. +unsafe { &*$crate::task::Task ::current () } + }; +}/// Wraps the kernel's `struct task_struct`. /// @@ -15,6 +25,42 @@ use core::ptr;/// /// Instances of this type are always ref-counted, that is, a call to `get_task_struct` ensures /// that the allocation remains valid at least until the matching call to `put_task_struct`. +/// +/// # Examples +/// +/// The following is an example of getting the PID of the current thread with zero additional cost +/// when compared to the C version: +/// +/// ``` +/// let pid = current!().pid(); +/// ``` +/// +/// Getting the PID of the current process, also zero additional cost: +/// +/// ``` +/// let pid = current!().group_leader().pid(); +/// ``` +/// +/// Getting the current task and storing it in some struct. The reference count is automatically +/// incremented when creating `State` and decremented when it is dropped: +/// +/// ``` +/// use kernel::{task::Task, types::ARef}; +/// +/// struct State { +/// creator: ARef<Task>, +/// index: u32, +/// } +/// +/// impl State { +/// fn new() -> Self { +/// Self { +/// creator: current!().into(), +/// index: 0, +/// } +/// } +/// } +/// ``` #[repr(transparent)] pub struct Task (pub (crate )Opaque <bindings::task_struct >);@@ -27,6 +73,46 @@ unsafe impl Sync for Task {}type Pid = bindings::pid_t ;impl Task { +/// Returns a task reference for the currently executing task/thread. +/// +/// The recommended way to get the current task/thread is to use the +/// [`current`](crate::current) macro because it is safe. +/// +/// # Safety +/// +/// Callers must ensure that the returned object doesn't outlive the current task/thread. +pub unsafe fn current () ->impl Deref <Target =Task > { +pub struct TaskRef <'a> { + task: &'aTask , + _not_send:PhantomData <*mut ()>, + } + +impl Deref for TaskRef <'_> { +type Target =Task ; + +fn deref (&self) -> &Self ::Target { + self.task + } + } + +impl From <TaskRef <'_>>for crate ::types::ARef <Task > {
Quoted 8 lines
rust/kernel/task.rs unsafe impl Sync for Task {} · line 102
Quoted 4 lines
rust/kernel/task.rs +4
-0+fn from (t:TaskRef <'_>) ->Self { + t.deref ().into () + } + }I think we can remove this
Fromimpl, since the type is never exposed to the outside (there still is theFrom<&T> for ARef<T>impl, so users can still docurrent!().into()to get anARef<Task>).
Hmm, this also allows me to remove the pub visibility from TaskRef. I will make this change for v4.
Quoted 24 lines
--
Cheers,
BennoQuoted 19 lines
rust/kernel/task.rs +13
-1+ +// SAFETY: Just an FFI call with no additional safety requirements. +let ptr =unsafe { bindings::get_current () }; + +TaskRef { +// SAFETY: If the current thread is still running, the current task is valid. Given +// that `TaskRef` is not `Send`, we know it cannot be transferred to another thread +// (where it could potentially outlive the caller). + task:unsafe { &*ptr.cast () }, + _not_send:PhantomData , + } + } +/// Returns the group leader of the given task. pub fn group_leader (&self) -> &Task {// SAFETY: By the type invariant, we know that `self.0` is a valid task. Valid tasks always --2.34.1
PATCH v3 11/13 rust: lock: add `Guard::do_unlocked`
In reply to Wedson Almeida FilhoFrom: Wedson Almeida Filho <[email protected]>
It releases the lock, executes some function provided by the caller, then reacquires the lock. This is preparation for the implementation of condvars, which will sleep after between unlocking and relocking.
We need an explicit relock method for primitives like SpinLock that have an irqsave variant: we use the guard state to determine if the lock was originally acquired with the regular lock function or lock_irqsave.
---
v1 -> v2: No changes
v2 -> v3: No changes
rust/kernel/sync/lock.rs | 25 +++++++++++++++++++++++++ rust/kernel/sync/lock/spinlock.rs | 17 +++++++++++++++-- 2 files changed, 40 insertions(+), 2 deletions(-)
rust/kernel/sync/lock.rs +25 -0
@@ -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.
@@ -164,6 +178,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
@@ -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
Re: [PATCH v3 11/13] rust: lock: add `Guard::do_unlocked`
Quoted 108 lines · 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
relockmethod for primitives likeSpinLockthat have an irqsave variant: we use the guard state to determine if the lock was originally acquired with the regularlockfunction orlock_irqsave.Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: No changes
v2 -> v3: No changesrust/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@@ -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. @@ -164,6 +178,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 +14
-1@@ -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) }, + }; + } }
rust/kernel/sync/lock/spinlock.rs unsafe impl super::Backend for SpinLockBackend { · line 152
Quoted 10 lines
rust/kernel/sync/lock/spinlock.rs +1
-1// 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.
PATCH v3 12/13 rust: sync: introduce `CondVar`
In reply to Wedson Almeida FilhoFrom: 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.
---
v1 -> v2: Use the new current macro
v2 -> v3: Use new Opaque::ffi_init from Benno's series
rust/bindings/bindings_helper.h | 1 + rust/helpers.c | 7 ++ rust/kernel/sync.rs | 2 + rust/kernel/sync/condvar.rs | 174 ++++++++++++++++++++++++++++++++ rust/kernel/sync/lock.rs | 1 - 5 files changed, 184 insertions(+), 1 deletion(-) create mode 100644 rust/kernel/sync/condvar.rs
rust/bindings/bindings_helper.h +1 -0
@@ -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
@@ -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
@@ -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 +174 -0
174 lines not on this page · raw message
rust/kernel/sync/lock.rs +0 -1
@@ -179,7 +179,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
Re: [PATCH v3 12/13] rust: sync: introduce `CondVar`
Quoted 125 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.
Cc Peter Zijlstra <[email protected]>Cc Ingo Molnar <[email protected]>Cc Will Deacon <[email protected]>Cc Waiman Long <[email protected]>Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: Use the newcurrentmacro
v2 -> v3: Use newOpaque::ffi_initfrom Benno's seriesrust/bindings/bindings_helper.h | 1 + rust/helpers.c | 7 ++ rust/kernel/sync.rs | 2 + rust/kernel/sync/condvar.rs | 174 ++++++++++++++++++++++++++++++++ rust/kernel/sync/lock.rs | 1 - 5 files changed, 184 insertions(+), 1 deletion(-) create mode 100644 rust/kernel/sync/condvar.rsrust/bindings/bindings_helper.h +1
-0@@ -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@@ -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@@ -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 +40
-0@@ -0,0 +1,174 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! A condition variable. +//! +//! This module allows Rust code to use the kernel's [`struct wait_queue_head`] as a condition +//! variable. + +use super ::{lock::Backend , lock::Guard ,LockClassKey }; +use crate ::{bindings, init::PinInit , pin_init, str::CStr , types::Opaque }; +use core::marker::PhantomPinned ; +use macros::pin_data; + +/// Creates a [`CondVar`] initialiser with the given name and a newly-created lock class. +#[macro_export] +macro_rules! new_condvar { + ($($name:literal)?) => { + $crate::sync::CondVar ::new ($crate::optional_name!($($name)?), $crate::static_lock_class!()) + }; +} + +/// 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. +/// +/// Instances of [`CondVar`] need a lock class and to be pinned. The recommended way to create such +/// instances is with the [`pin_init`](crate::pin_init) and [`new_condvar`] macros. +/// +/// # Examples +/// +/// The following is an example of using a condvar with a mutex: +/// +/// ``` +/// use kernel::sync::{CondVar, Mutex}; +/// use kernel::{new_condvar, new_mutex}; +/// +/// #[pin_data]
rust/kernel/sync/condvar.rs line 50
Quoted 10 lines
rust/kernel/sync/condvar.rs new file +10
-0+/// pub struct Example { +/// #[pin] +/// value: Mutex<u32>, +/// +/// #[pin] +/// value_changed: CondVar, +/// } +/// +/// /// Waits for `e.value` to become `v`. +/// fn wait_for_vaue(e: &Example, v: u32) {
Should it be wait_for_value?
Quoted 129 lines
rust/kernel/sync/condvar.rs new file +124
-0+/// let mut guard = e.value.lock(); +/// while *guard != v { +/// e.value_changed.wait_uninterruptible(&mut guard); +/// } +/// } +/// +/// /// Increments `e.value` and notifies all potential waiters. +/// fn increment(e: &Example) { +/// *e.value.lock() += 1; +/// e.value_changed.notify_all(); +/// } +/// +/// /// Allocates a new boxed `Example`. +/// fn new_example() -> Result<Pin<Box<Example>>> { +/// Box::pin_init(pin_init!(Example { +/// value <- new_mutex!(0), +/// value_changed <- new_condvar!(), +/// })) +/// } +/// ``` +/// +/// [`struct wait_queue_head`]: ../../../include/linux/wait.h +#[pin_data] +pub struct CondVar { +#[pin] +pub (crate ) wait_list:Opaque <bindings::wait_queue_head >, + +/// A condvar needs to be pinned because it contains a [`struct list_head`] that is +/// self-referential, so it cannot be safely moved once it is initialised. +#[pin] + _pin:PhantomPinned , +} + +// SAFETY: `CondVar` only uses a `struct wait_queue_head`, which is safe to use on any thread. +#[allow(clippy::non_send_fields_in_send_ty)] +unsafe impl Send for CondVar {} + +// SAFETY: `CondVar` only uses a `struct wait_queue_head`, which is safe to use on multiple threads +// concurrently. +unsafe impl Sync for CondVar {} + +impl CondVar { +/// Constructs a new condvar initialiser. +#[allow(clippy::new_ret_no_self)] +pub fn new (name: &'staticCStr , key: &'staticLockClassKey ) ->impl PinInit <Self > { +pin_init! (Self { + _pin:PhantomPinned , +// SAFETY: `slot` is valid while the closure is called and both `name` and `key` have +// static lifetimes so they live indefinitely. + wait_list <-Opaque ::ffi_init (|slot|unsafe { + bindings::__init_waitqueue_head (slot, name.as_char_ptr (), key.as_ptr ()) + }), + }) + } + +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_stateas _ ) + }; + +// 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); +crate ::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, + flagsas _ , + ) + }; + } + +/// 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 ); + } +}rust/kernel/sync/lock.rs +0
-0
rust/kernel/sync/lock.rs pub struct Guard<'a, T: ?Sized, B: Backend> { · line 184
Quoted 7 lines
rust/kernel/sync/lock.rs +0
-1@@ -179,7 +179,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) };
Re: [PATCH v3 12/13] rust: sync: introduce `CondVar`
Quoted 131 lines · Martin Rodriguez Reboredo
Quoted 129 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.
Cc Peter Zijlstra <[email protected]>Cc Ingo Molnar <[email protected]>Cc Will Deacon <[email protected]>Cc Waiman Long <[email protected]>Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: Use the newcurrentmacro
v2 -> v3: Use newOpaque::ffi_initfrom Benno's seriesrust/bindings/bindings_helper.h | 1 + rust/helpers.c | 7 ++ rust/kernel/sync.rs | 2 + rust/kernel/sync/condvar.rs | 174 ++++++++++++++++++++++++++++++++ rust/kernel/sync/lock.rs | 1 - 5 files changed, 184 insertions(+), 1 deletion(-) create mode 100644 rust/kernel/sync/condvar.rsrust/bindings/bindings_helper.h +1
-0@@ -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@@ -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@@ -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 +44
-0@@ -0,0 +1,174 @@ +// SPDX-License-Identifier: GPL-2.0 + +//! A condition variable. +//! +//! This module allows Rust code to use the kernel's [`struct wait_queue_head`] as a condition +//! variable. + +use super ::{lock::Backend , lock::Guard ,LockClassKey }; +use crate ::{bindings, init::PinInit , pin_init, str::CStr , types::Opaque }; +use core::marker::PhantomPinned ; +use macros::pin_data; + +/// Creates a [`CondVar`] initialiser with the given name and a newly-created lock class. +#[macro_export] +macro_rules! new_condvar { + ($($name:literal)?) => { + $crate::sync::CondVar ::new ($crate::optional_name!($($name)?), $crate::static_lock_class!()) + }; +} + +/// 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. +/// +/// Instances of [`CondVar`] need a lock class and to be pinned. The recommended way to create such +/// instances is with the [`pin_init`](crate::pin_init) and [`new_condvar`] macros. +/// +/// # Examples +/// +/// The following is an example of using a condvar with a mutex: +/// +/// ``` +/// use kernel::sync::{CondVar, Mutex}; +/// use kernel::{new_condvar, new_mutex}; +/// +/// #[pin_data] +/// pub struct Example { +/// #[pin] +/// value: Mutex<u32>, +///
Quoted 8 lines
rust/kernel/sync/condvar.rs line 50
Quoted 6 lines
rust/kernel/sync/condvar.rs new file +6
-0+/// #[pin] +/// value_changed: CondVar, +/// } +/// +/// /// Waits for `e.value` to become `v`. +/// fn wait_for_vaue(e: &Example, v: u32) { Should it be
wait_for_value?
Yes, thanks for spotting this. Will fix.
Quoted 139 lines
Quoted 130 lines
rust/kernel/sync/condvar.rs new file +124
-0+/// let mut guard = e.value.lock(); +/// while *guard != v { +/// e.value_changed.wait_uninterruptible(&mut guard); +/// } +/// } +/// +/// /// Increments `e.value` and notifies all potential waiters. +/// fn increment(e: &Example) { +/// *e.value.lock() += 1; +/// e.value_changed.notify_all(); +/// } +/// +/// /// Allocates a new boxed `Example`. +/// fn new_example() -> Result<Pin<Box<Example>>> { +/// Box::pin_init(pin_init!(Example { +/// value <- new_mutex!(0), +/// value_changed <- new_condvar!(), +/// })) +/// } +/// ``` +/// +/// [`struct wait_queue_head`]: ../../../include/linux/wait.h +#[pin_data] +pub struct CondVar { +#[pin] +pub (crate ) wait_list:Opaque <bindings::wait_queue_head >, + +/// A condvar needs to be pinned because it contains a [`struct list_head`] that is +/// self-referential, so it cannot be safely moved once it is initialised. +#[pin] + _pin:PhantomPinned , +} + +// SAFETY: `CondVar` only uses a `struct wait_queue_head`, which is safe to use on any thread. +#[allow(clippy::non_send_fields_in_send_ty)] +unsafe impl Send for CondVar {} + +// SAFETY: `CondVar` only uses a `struct wait_queue_head`, which is safe to use on multiple threads +// concurrently. +unsafe impl Sync for CondVar {} + +impl CondVar { +/// Constructs a new condvar initialiser. +#[allow(clippy::new_ret_no_self)] +pub fn new (name: &'staticCStr , key: &'staticLockClassKey ) ->impl PinInit <Self > { +pin_init! (Self { + _pin:PhantomPinned , +// SAFETY: `slot` is valid while the closure is called and both `name` and `key` have +// static lifetimes so they live indefinitely. + wait_list <-Opaque ::ffi_init (|slot|unsafe { + bindings::__init_waitqueue_head (slot, name.as_char_ptr (), key.as_ptr ()) + }), + }) + } + +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_stateas _ ) + }; + +// 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); +crate ::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, + flagsas _ , + ) + }; + } + +/// 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 ); + } +}rust/kernel/sync/lock.rs +0
-0rust/kernel/sync/lock.rs pub struct Guard<'a, T: ?Sized, B: Backend> { · line 184
Quoted 7 lines
rust/kernel/sync/lock.rs +0
-1@@ -179,7 +179,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) };Reviewed-by Martin Rodriguez Reboredo <[email protected]>
PATCH v3 13/13 rust: sync: introduce `LockedBy`
In reply to Wedson Almeida FilhoFrom: Wedson Almeida Filho <[email protected]>
This allows us to have data protected by a lock despite not being wrapped by it. Access is granted by providing evidence that the lock is held by the caller.
---
v1 -> v2: Added build_assert to rule out zero-sized types v2 -> v3: Improve comments around panics and support for ZSTs
rust/kernel/sync.rs | 2 + rust/kernel/sync/lock.rs | 2 +- rust/kernel/sync/locked_by.rs | 147 ++++++++++++++++++++++++++++++++++ 3 files changed, 150 insertions(+), 1 deletion(-) create mode 100644 rust/kernel/sync/locked_by.rs
rust/kernel/sync.rs +2 -0
@@ -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
@@ -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 +147 -0
147 lines not on this page · raw message
Signature · 1 line
2.34.1
Re: [PATCH v3 13/13] rust: sync: introduce `LockedBy`
Quoted 190 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.
Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: Addedbuild_assertto rule out zero-sized types v2 -> v3: Improve comments around panics and support for ZSTsrust/kernel/sync.rs | 2 + rust/kernel/sync/lock.rs | 2 +- rust/kernel/sync/locked_by.rs | 147 ++++++++++++++++++++++++++++++++++ 3 files changed, 150 insertions(+), 1 deletion(-) create mode 100644 rust/kernel/sync/locked_by.rsrust/kernel/sync.rs +2
-0@@ -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@@ -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 +137
-0@@ -0,0 +1,147 @@ +// 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. It panics if the evidence +/// refers to the wrong instance of the lock. +/// +/// # Examples +/// +/// The following is an example for illustrative purposes: `InnerDirectory::bytes_used` is an +/// aggregate of all `InnerFile::bytes_used` and must be kept consistent; so we wrap `InnerFile` in +/// a `LockedBy` so that it shares a lock with `InnerDirectory`. This allows us to enforce at +/// compile-time that access to `InnerFile` is only granted when an `InnerDirectory` is also +/// locked; we enforce at run time that the right `InnerDirectory` is locked. +/// +/// ``` +/// use kernel::sync::{LockedBy, Mutex}; +/// +/// struct InnerFile { +/// bytes_used: u64, +/// } +/// +/// struct File { +/// _ino: u32, +/// inner: LockedBy<InnerFile, InnerDirectory>, +/// } +/// +/// struct InnerDirectory { +/// /// The sum of the bytes used by all files. +/// bytes_used: u64, +/// _files: Vec<File>, +/// } +/// +/// struct Directory { +/// _ino: u32, +/// inner: Mutex<InnerDirectory>, +/// } +/// +/// /// Prints `bytes_used` from both the directory and file. +/// fn print_bytes_used(dir: &Directory, file: &File) { +/// let guard = dir.inner.lock(); +/// let inner_file = file.inner.access(&guard); +/// pr_info!("{} {}", guard.bytes_used, inner_file.bytes_used); +/// } +/// +/// /// Increments `bytes_used` for both the directory and file. +/// fn inc_bytes_used(dir: &Directory, file: &File) { +/// let mut guard = dir.inner.lock(); +/// guard.bytes_used += 10; +/// +/// let file_inner = file.inner.access_mut(&mut guard); +/// file_inner.bytes_used += 10; +/// } +/// +/// /// Creates a new file. +/// fn new_file(ino: u32, dir: &Directory) -> File { +/// File { +/// _ino: ino, +/// inner: LockedBy::new(&dir.inner, InnerFile { bytes_used: 0 }), +/// } +/// } +/// ``` +pub struct LockedBy <T : ?Sized ,U : ?Sized > { + owner: *const U , + data:UnsafeCell <T >, +} + +// SAFETY: `LockedBy` can be transferred across thread boundaries iff the data it protects can. +unsafe impl <T : ?Sized +Send ,U : ?Sized >Send for LockedBy <T ,U > {} + +// SAFETY: `LockedBy` serialises the interior mutability it provides, so it is `Sync` as long as the +// data it protects is `Send`. +unsafe impl <T : ?Sized +Send ,U : ?Sized >Sync for LockedBy <T ,U > {} + +impl <T ,U : ?Sized >LockedBy <T ,U > { +/// Constructs a new instance of [`LockedBy`]. +/// +/// It stores a raw pointer to the owner that is never dereferenced. It is only used to ensure +/// that the right owner is being used to access the protected data. If the owner is freed, the +/// 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 >LockedBy <T ,U > { +/// Returns a reference to the protected data when the caller provides evidence (via a +/// reference) that the owner is locked. +/// +/// `U` cannot be a zero-sized type (ZST) because there are ways to get an `&U` that matches +/// the data protected by the lock without actually holding it. +/// +/// # Panics +/// +/// Panics if `owner` is different from the data protected by the lock used in +/// [`new`](LockedBy::new). +pub fn access <'a>(&'a self, owner: &'aU ) -> &'aT { +// Detect the usage of SZTs, which are supported, at compile time. +crate ::build_assert!(core::mem::size_of ::<U >() >0 ); +if !ptr::eq (owner, self.owner) { +panic! ("mismatched owners" ); + } + +// SAFETY: `owner` is evidence that the owner is locked. +unsafe { &*self.data.get () } + } + +/// Returns a mutable reference to the protected data when the caller provides evidence (via a +/// mutable owner) that the owner is locked mutably. +/// +/// `U` cannot be a zero-sized type (ZST) because there are ways to get an `&mut U` that +/// matches the data protected by the lock without actually holding it. +/// +/// Showing a mutable reference to the owner is sufficient because we know no other references +/// can exist to it. +/// +/// # Panics +/// +/// Panics if `owner` is different from the data protected by the lock used in +/// [`new`](LockedBy::new). +pub fn access_mut <'a>(&'a self, owner: &'amut U ) -> &'amut T {
rust/kernel/sync/locked_by.rs line 147
Quoted 10 lines
rust/kernel/sync/locked_by.rs new file +10
-0+// Detect the usage of SZTs, which are supported, at compile time. +crate ::build_assert!(core::mem::size_of ::<U >() >0 ); +if !ptr::eq (owner, self.owner) { +panic! ("mismatched owners" ); + } + +// SAFETY: `owner` is evidence that there is only one reference to the owner. +unsafe { &mut *self.data.get () } + } +}
Re: [PATCH v3 13/13] rust: sync: introduce `LockedBy`
In reply to Wedson Almeida FilhoQuoted 139 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.
Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: Addedbuild_assertto rule out zero-sized types v2 -> v3: Improve comments around panics and support for ZSTsrust/kernel/sync.rs | 2 + rust/kernel/sync/lock.rs | 2 +- rust/kernel/sync/locked_by.rs | 147 ++++++++++++++++++++++++++++++++++ 3 files changed, 150 insertions(+), 1 deletion(-) create mode 100644 rust/kernel/sync/locked_by.rsrust/kernel/sync.rs +2
-0@@ -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@@ -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 +86
-0@@ -0,0 +1,147 @@ +// 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. It panics if the evidence +/// refers to the wrong instance of the lock. +/// +/// # Examples +/// +/// The following is an example for illustrative purposes: `InnerDirectory::bytes_used` is an +/// aggregate of all `InnerFile::bytes_used` and must be kept consistent; so we wrap `InnerFile` in +/// a `LockedBy` so that it shares a lock with `InnerDirectory`. This allows us to enforce at +/// compile-time that access to `InnerFile` is only granted when an `InnerDirectory` is also +/// locked; we enforce at run time that the right `InnerDirectory` is locked. +/// +/// ``` +/// use kernel::sync::{LockedBy, Mutex}; +/// +/// struct InnerFile { +/// bytes_used: u64, +/// } +/// +/// struct File { +/// _ino: u32, +/// inner: LockedBy<InnerFile, InnerDirectory>, +/// } +/// +/// struct InnerDirectory { +/// /// The sum of the bytes used by all files. +/// bytes_used: u64, +/// _files: Vec<File>, +/// } +/// +/// struct Directory { +/// _ino: u32, +/// inner: Mutex<InnerDirectory>, +/// } +/// +/// /// Prints `bytes_used` from both the directory and file. +/// fn print_bytes_used(dir: &Directory, file: &File) { +/// let guard = dir.inner.lock(); +/// let inner_file = file.inner.access(&guard); +/// pr_info!("{} {}", guard.bytes_used, inner_file.bytes_used); +/// } +/// +/// /// Increments `bytes_used` for both the directory and file. +/// fn inc_bytes_used(dir: &Directory, file: &File) { +/// let mut guard = dir.inner.lock(); +/// guard.bytes_used += 10; +/// +/// let file_inner = file.inner.access_mut(&mut guard); +/// file_inner.bytes_used += 10; +/// } +/// +/// /// Creates a new file. +/// fn new_file(ino: u32, dir: &Directory) -> File { +/// File { +/// _ino: ino, +/// inner: LockedBy::new(&dir.inner, InnerFile { bytes_used: 0 }), +/// } +/// } +/// ``` +pub struct LockedBy <T : ?Sized ,U : ?Sized > { + owner: *const U , + data:UnsafeCell <T >, +} + +// SAFETY: `LockedBy` can be transferred across thread boundaries iff the data it protects can. +unsafe impl <T : ?Sized +Send ,U : ?Sized >Send for LockedBy <T ,U > {} + +// SAFETY: `LockedBy` serialises the interior mutability it provides, so it is `Sync` as long as the +// data it protects is `Send`. +unsafe impl <T : ?Sized +Send ,U : ?Sized >Sync for LockedBy <T ,U > {} + +impl <T ,U : ?Sized >LockedBy <T ,U > {
rust/kernel/sync/locked_by.rs line 96
Quoted 10 lines
rust/kernel/sync/locked_by.rs new file +10
-0+/// 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 (),
Given we use the address of the data as a key to verify holding a lock, I think we should use Pin<_> in the function signature, i.e.
pub fn new(owner: Pin<&Lock<U, impl Backend>, data: T) -> Self {
Self {
owner: owner.get_ref().data.get()
data: UnsafeCell::new(data),
}
}Thoughts?
Regards,
Boqun
Quoted 54 lines
rust/kernel/sync/locked_by.rs new file +51
-0+ data: UnsafeCell::new(data), + } + } +} + +impl <T : ?Sized ,U >LockedBy <T ,U > { +/// Returns a reference to the protected data when the caller provides evidence (via a +/// reference) that the owner is locked. +/// +/// `U` cannot be a zero-sized type (ZST) because there are ways to get an `&U` that matches +/// the data protected by the lock without actually holding it. +/// +/// # Panics +/// +/// Panics if `owner` is different from the data protected by the lock used in +/// [`new`](LockedBy::new). +pub fn access <'a>(&'a self, owner: &'aU ) -> &'aT { +// Detect the usage of SZTs, which are supported, at compile time. +crate ::build_assert!(core::mem::size_of ::<U >() >0 ); +if !ptr::eq (owner, self.owner) { +panic! ("mismatched owners" ); + } + +// SAFETY: `owner` is evidence that the owner is locked. +unsafe { &*self.data.get () } + } + +/// Returns a mutable reference to the protected data when the caller provides evidence (via a +/// mutable owner) that the owner is locked mutably. +/// +/// `U` cannot be a zero-sized type (ZST) because there are ways to get an `&mut U` that +/// matches the data protected by the lock without actually holding it. +/// +/// Showing a mutable reference to the owner is sufficient because we know no other references +/// can exist to it. +/// +/// # Panics +/// +/// Panics if `owner` is different from the data protected by the lock used in +/// [`new`](LockedBy::new). +pub fn access_mut <'a>(&'a self, owner: &'amut U ) -> &'amut T { +// Detect the usage of SZTs, which are supported, at compile time. +crate ::build_assert!(core::mem::size_of ::<U >() >0 ); +if !ptr::eq (owner, self.owner) { +panic! ("mismatched owners" ); + } + +// SAFETY: `owner` is evidence that there is only one reference to the owner. +unsafe { &mut *self.data.get () } + } +}Signature · 1 line
2.34.1
Re: [PATCH v3 13/13] rust: sync: introduce `LockedBy`
Quoted 154 lines · Boqun Feng
Quoted 139 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.
Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: Addedbuild_assertto rule out zero-sized types v2 -> v3: Improve comments around panics and support for ZSTsrust/kernel/sync.rs | 2 + rust/kernel/sync/lock.rs | 2 +- rust/kernel/sync/locked_by.rs | 147 ++++++++++++++++++++++++++++++++++ 3 files changed, 150 insertions(+), 1 deletion(-) create mode 100644 rust/kernel/sync/locked_by.rsrust/kernel/sync.rs +2
-0@@ -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@@ -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 +86
-0@@ -0,0 +1,147 @@ +// 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. It panics if the evidence +/// refers to the wrong instance of the lock. +/// +/// # Examples +/// +/// The following is an example for illustrative purposes: `InnerDirectory::bytes_used` is an +/// aggregate of all `InnerFile::bytes_used` and must be kept consistent; so we wrap `InnerFile` in +/// a `LockedBy` so that it shares a lock with `InnerDirectory`. This allows us to enforce at +/// compile-time that access to `InnerFile` is only granted when an `InnerDirectory` is also +/// locked; we enforce at run time that the right `InnerDirectory` is locked. +/// +/// ``` +/// use kernel::sync::{LockedBy, Mutex}; +/// +/// struct InnerFile { +/// bytes_used: u64, +/// } +/// +/// struct File { +/// _ino: u32, +/// inner: LockedBy<InnerFile, InnerDirectory>, +/// } +/// +/// struct InnerDirectory { +/// /// The sum of the bytes used by all files. +/// bytes_used: u64, +/// _files: Vec<File>, +/// } +/// +/// struct Directory { +/// _ino: u32, +/// inner: Mutex<InnerDirectory>, +/// } +/// +/// /// Prints `bytes_used` from both the directory and file. +/// fn print_bytes_used(dir: &Directory, file: &File) { +/// let guard = dir.inner.lock(); +/// let inner_file = file.inner.access(&guard); +/// pr_info!("{} {}", guard.bytes_used, inner_file.bytes_used); +/// } +/// +/// /// Increments `bytes_used` for both the directory and file. +/// fn inc_bytes_used(dir: &Directory, file: &File) { +/// let mut guard = dir.inner.lock(); +/// guard.bytes_used += 10; +/// +/// let file_inner = file.inner.access_mut(&mut guard); +/// file_inner.bytes_used += 10; +/// } +/// +/// /// Creates a new file. +/// fn new_file(ino: u32, dir: &Directory) -> File { +/// File { +/// _ino: ino, +/// inner: LockedBy::new(&dir.inner, InnerFile { bytes_used: 0 }), +/// } +/// } +/// ``` +pub struct LockedBy <T : ?Sized ,U : ?Sized > { + owner: *const U , + data:UnsafeCell <T >, +} + +// SAFETY: `LockedBy` can be transferred across thread boundaries iff the data it protects can. +unsafe impl <T : ?Sized +Send ,U : ?Sized >Send for LockedBy <T ,U > {} + +// SAFETY: `LockedBy` serialises the interior mutability it provides, so it is `Sync` as long as the +// data it protects is `Send`. +unsafe impl <T : ?Sized +Send ,U : ?Sized >Sync for LockedBy <T ,U > {} + +impl <T ,U : ?Sized >LockedBy <T ,U > {rust/kernel/sync/locked_by.rs line 96
Quoted 10 lines
rust/kernel/sync/locked_by.rs new file +10
-0+/// 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 (),Given we use the address of the
dataas a key to verify holding a lock, I think we should usePin<_>in the function signature, i.e.
Quoted 9 lines
pub fn new(owner: Pin<&Lock<U, impl Backend>, data: T) -> Self { Self { owner: owner.get_ref().data.get() data: UnsafeCell::new(data), } }Thoughts?
Nevermind for now, since Lock is a pin-inited type, we can revisit this later.
Regards,
Boqun
Quoted 57 lines
Regards,
BoqunQuoted 54 lines
rust/kernel/sync/locked_by.rs new file +51
-0+ data: UnsafeCell::new(data), + } + } +} + +impl <T : ?Sized ,U >LockedBy <T ,U > { +/// Returns a reference to the protected data when the caller provides evidence (via a +/// reference) that the owner is locked. +/// +/// `U` cannot be a zero-sized type (ZST) because there are ways to get an `&U` that matches +/// the data protected by the lock without actually holding it. +/// +/// # Panics +/// +/// Panics if `owner` is different from the data protected by the lock used in +/// [`new`](LockedBy::new). +pub fn access <'a>(&'a self, owner: &'aU ) -> &'aT { +// Detect the usage of SZTs, which are supported, at compile time. +crate ::build_assert!(core::mem::size_of ::<U >() >0 ); +if !ptr::eq (owner, self.owner) { +panic! ("mismatched owners" ); + } + +// SAFETY: `owner` is evidence that the owner is locked. +unsafe { &*self.data.get () } + } + +/// Returns a mutable reference to the protected data when the caller provides evidence (via a +/// mutable owner) that the owner is locked mutably. +/// +/// `U` cannot be a zero-sized type (ZST) because there are ways to get an `&mut U` that +/// matches the data protected by the lock without actually holding it. +/// +/// Showing a mutable reference to the owner is sufficient because we know no other references +/// can exist to it. +/// +/// # Panics +/// +/// Panics if `owner` is different from the data protected by the lock used in +/// [`new`](LockedBy::new). +pub fn access_mut <'a>(&'a self, owner: &'amut U ) -> &'amut T { +// Detect the usage of SZTs, which are supported, at compile time. +crate ::build_assert!(core::mem::size_of ::<U >() >0 ); +if !ptr::eq (owner, self.owner) { +panic! ("mismatched owners" ); + } + +// SAFETY: `owner` is evidence that there is only one reference to the owner. +unsafe { &mut *self.data.get () } + } +}Signature · 1 line
2.34.1
Re: [PATCH v3 13/13] rust: sync: introduce `LockedBy`
In reply to Wedson Almeida FilhoQuoted 61 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.
Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: Addedbuild_assertto rule out zero-sized types v2 -> v3: Improve comments around panics and support for ZSTsrust/kernel/sync.rs | 2 + rust/kernel/sync/lock.rs | 2 +- rust/kernel/sync/locked_by.rs | 147 ++++++++++++++++++++++++++++++++++ 3 files changed, 150 insertions(+), 1 deletion(-)create mode 100644
rust/kernel/sync/locked_by.rsrust/kernel/sync.rs +2
-0@@ -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@@ -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 +8
-0@@ -0,0 +1,147 @@ +// 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.
rust/kernel/sync/locked_by.rs line 18
Quoted 10 lines
rust/kernel/sync/locked_by.rs new file +10
-0+/// +/// 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. It panics if the evidence +/// refers to the wrong instance of the lock. +///
Maybe add a small section that ZSTs are not allowed for U, since they do not have to have unique addresses.
Quoted 66 lines
rust/kernel/sync/locked_by.rs new file +66
-0+/// # Examples +/// +/// The following is an example for illustrative purposes: `InnerDirectory::bytes_used` is an +/// aggregate of all `InnerFile::bytes_used` and must be kept consistent; so we wrap `InnerFile` in +/// a `LockedBy` so that it shares a lock with `InnerDirectory`. This allows us to enforce at +/// compile-time that access to `InnerFile` is only granted when an `InnerDirectory` is also +/// locked; we enforce at run time that the right `InnerDirectory` is locked. +/// +/// ``` +/// use kernel::sync::{LockedBy, Mutex}; +/// +/// struct InnerFile { +/// bytes_used: u64, +/// } +/// +/// struct File { +/// _ino: u32, +/// inner: LockedBy<InnerFile, InnerDirectory>, +/// } +/// +/// struct InnerDirectory { +/// /// The sum of the bytes used by all files. +/// bytes_used: u64, +/// _files: Vec<File>, +/// } +/// +/// struct Directory { +/// _ino: u32, +/// inner: Mutex<InnerDirectory>, +/// } +/// +/// /// Prints `bytes_used` from both the directory and file. +/// fn print_bytes_used(dir: &Directory, file: &File) { +/// let guard = dir.inner.lock(); +/// let inner_file = file.inner.access(&guard); +/// pr_info!("{} {}", guard.bytes_used, inner_file.bytes_used); +/// } +/// +/// /// Increments `bytes_used` for both the directory and file. +/// fn inc_bytes_used(dir: &Directory, file: &File) { +/// let mut guard = dir.inner.lock(); +/// guard.bytes_used += 10; +/// +/// let file_inner = file.inner.access_mut(&mut guard); +/// file_inner.bytes_used += 10; +/// } +/// +/// /// Creates a new file. +/// fn new_file(ino: u32, dir: &Directory) -> File { +/// File { +/// _ino: ino, +/// inner: LockedBy::new(&dir.inner, InnerFile { bytes_used: 0 }), +/// } +/// } +/// ``` +pub struct LockedBy <T : ?Sized ,U : ?Sized > { + owner: *const U , + data:UnsafeCell <T >, +} + +// SAFETY: `LockedBy` can be transferred across thread boundaries iff the data it protects can. +unsafe impl <T : ?Sized +Send ,U : ?Sized >Send for LockedBy <T ,U > {} + +// SAFETY: `LockedBy` serialises the interior mutability it provides, so it is `Sync` as long as the +// data it protects is `Send`. +unsafe impl <T : ?Sized +Send ,U : ?Sized >Sync for LockedBy <T ,U > {}
rust/kernel/sync/locked_by.rs line 94
Quoted 10 lines
rust/kernel/sync/locked_by.rs new file +10
-0+ +impl <T ,U : ?Sized >LockedBy <T ,U > { +/// Constructs a new instance of [`LockedBy`]. +/// +/// It stores a raw pointer to the owner that is never dereferenced. It is only used to ensure +/// that the right owner is being used to access the protected data. If the owner is freed, the +/// data becomes inaccessible; if another instance of the owner is allocated *on the same +/// memory location*, the data becomes accessible again: none of this affects memory safety +/// because in any case at most one thread (or CPU) can access the protected data at a time. +pub fn new (owner: &Lock <U ,impl Backend >, data:T ) ->Self {
I suggested this already on v2, but I think it was to late, since you quickly sent v3 after I sent my reply, so reiterating the point here.
I think we should have build_assert!(mem::size_of::<Lock<T, B>>() > 0) here to ensure that you cannot have two locks referring to the same memory location.
This is rather pedantic, since I doubt that we would introduce a Backend that has a ZST as the State, but it also does not hurt and might prevent a hard to identify bug later.
Quoted 10 lines
rust/kernel/sync/locked_by.rs new file +10
-0+Self { + owner: owner.data.get (), + data:UnsafeCell ::new (data), + } + } +} + +impl <T : ?Sized ,U >LockedBy <T ,U > { +/// Returns a reference to the protected data when the caller provides evidence (via a +/// reference) that the owner is locked.
rust/kernel/sync/locked_by.rs line 114
Quoted 10 lines
rust/kernel/sync/locked_by.rs new file +10
-0+/// +/// `U` cannot be a zero-sized type (ZST) because there are ways to get an `&U` that matches +/// the data protected by the lock without actually holding it. +/// +/// # Panics +/// +/// Panics if `owner` is different from the data protected by the lock used in +/// [`new`](LockedBy::new). +pub fn access <'a>(&'a self, owner: &'aU ) -> &'aT { +// Detect the usage of SZTs, which are supported, at compile time.
Typos: "SZTs" -> "ZSTs" and "supported" -> "unsupported"? Also found below.
rust/kernel/sync/locked_by.rs line 115
Quoted 1 line
rust/kernel/sync/locked_by.rs new file +1
-0+crate ::build_assert!(core::mem::size_of ::<U >() >0 );
Could you add a meaningful error message here? Like "Cannot use LockedBy where U is a ZST, since it does not guarantee address uniqueness."
Also add this in the calls to build_assert! below and above.
--
Cheers,
Benno
Quoted 35 lines
rust/kernel/sync/locked_by.rs new file +32
-1+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. +/// +/// `U` cannot be a zero-sized type (ZST) because there are ways to get an `&mut U` that +/// matches the data protected by the lock without actually holding it. +/// +/// Showing a mutable reference to the owner is sufficient because we know no other references +/// can exist to it. +/// +/// # Panics +/// +/// Panics if `owner` is different from the data protected by the lock used in +/// [`new`](LockedBy::new). +pub fn access_mut <'a>(&'a self, owner: &'amut U ) -> &'amut T { +// Detect the usage of SZTs, which are supported, at compile time. +crate ::build_assert!(core::mem::size_of ::<U >() >0 ); +if !ptr::eq (owner, self.owner) { +panic! ("mismatched owners" ); + } + +// SAFETY: `owner` is evidence that there is only one reference to the owner. +unsafe { &mut *self.data.get () } + } +} --2.34.1
Re: [PATCH v3 13/13] rust: sync: introduce `LockedBy`
Quoted 67 lines · Benno Lossin
Quoted 66 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.
Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: Addedbuild_assertto rule out zero-sized types v2 -> v3: Improve comments around panics and support for ZSTsrust/kernel/sync.rs | 2 + rust/kernel/sync/lock.rs | 2 +- rust/kernel/sync/locked_by.rs | 147 ++++++++++++++++++++++++++++++++++ 3 files changed, 150 insertions(+), 1 deletion(-)create mode 100644
rust/kernel/sync/locked_by.rsrust/kernel/sync.rs +2
-0@@ -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@@ -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 +13
-0@@ -0,0 +1,147 @@ +// 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.
Quoted 8 lines
rust/kernel/sync/locked_by.rs line 18
Quoted 5 lines
rust/kernel/sync/locked_by.rs new file +5
-0+/// +/// [`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. It panics if the evidence +/// refers to the wrong instance of the lock. +/// Maybe add a small section that ZSTs are not allowed for
U, since they do not have to have unique addresses.
As I said on the previous message, the restriction that U cannot be a ZST is a restriction of access and access_mut, it's not one of the struct. Therefore, I don't think it belongs here.
In v3, I did add a small paragraph to both access and access_mut to reflect this.
Quoted 80 lines
Quoted 66 lines
rust/kernel/sync/locked_by.rs new file +66
-0+/// # Examples +/// +/// The following is an example for illustrative purposes: `InnerDirectory::bytes_used` is an +/// aggregate of all `InnerFile::bytes_used` and must be kept consistent; so we wrap `InnerFile` in +/// a `LockedBy` so that it shares a lock with `InnerDirectory`. This allows us to enforce at +/// compile-time that access to `InnerFile` is only granted when an `InnerDirectory` is also +/// locked; we enforce at run time that the right `InnerDirectory` is locked. +/// +/// ``` +/// use kernel::sync::{LockedBy, Mutex}; +/// +/// struct InnerFile { +/// bytes_used: u64, +/// } +/// +/// struct File { +/// _ino: u32, +/// inner: LockedBy<InnerFile, InnerDirectory>, +/// } +/// +/// struct InnerDirectory { +/// /// The sum of the bytes used by all files. +/// bytes_used: u64, +/// _files: Vec<File>, +/// } +/// +/// struct Directory { +/// _ino: u32, +/// inner: Mutex<InnerDirectory>, +/// } +/// +/// /// Prints `bytes_used` from both the directory and file. +/// fn print_bytes_used(dir: &Directory, file: &File) { +/// let guard = dir.inner.lock(); +/// let inner_file = file.inner.access(&guard); +/// pr_info!("{} {}", guard.bytes_used, inner_file.bytes_used); +/// } +/// +/// /// Increments `bytes_used` for both the directory and file. +/// fn inc_bytes_used(dir: &Directory, file: &File) { +/// let mut guard = dir.inner.lock(); +/// guard.bytes_used += 10; +/// +/// let file_inner = file.inner.access_mut(&mut guard); +/// file_inner.bytes_used += 10; +/// } +/// +/// /// Creates a new file. +/// fn new_file(ino: u32, dir: &Directory) -> File { +/// File { +/// _ino: ino, +/// inner: LockedBy::new(&dir.inner, InnerFile { bytes_used: 0 }), +/// } +/// } +/// ``` +pub struct LockedBy <T : ?Sized ,U : ?Sized > { + owner: *const U , + data:UnsafeCell <T >, +} + +// SAFETY: `LockedBy` can be transferred across thread boundaries iff the data it protects can. +unsafe impl <T : ?Sized +Send ,U : ?Sized >Send for LockedBy <T ,U > {} + +// SAFETY: `LockedBy` serialises the interior mutability it provides, so it is `Sync` as long as the +// data it protects is `Send`. +unsafe impl <T : ?Sized +Send ,U : ?Sized >Sync for LockedBy <T ,U > {}rust/kernel/sync/locked_by.rs line 94
Quoted 10 lines
rust/kernel/sync/locked_by.rs new file +10
-0+ +impl <T ,U : ?Sized >LockedBy <T ,U > { +/// Constructs a new instance of [`LockedBy`]. +/// +/// It stores a raw pointer to the owner that is never dereferenced. It is only used to ensure +/// that the right owner is being used to access the protected data. If the owner is freed, the +/// data becomes inaccessible; if another instance of the owner is allocated *on the same +/// memory location*, the data becomes accessible again: none of this affects memory safety +/// because in any case at most one thread (or CPU) can access the protected data at a time. +pub fn new (owner: &Lock <U ,impl Backend >, data:T ) ->Self {I suggested this already on v2, but I think it was to late, since you quickly sent v3 after I sent my reply, so reiterating the point here.
Quoted 3 lines
I think we should have
build_assert!(mem::size_of::<Lock<T, B>>() > 0)here to ensure that you cannot have two locks referring to the same memory location.
Ok, I'll add this to v4.
Quoted 18 lines
This is rather pedantic, since I doubt that we would introduce a
Backendthat has a ZST as theState, but it also does not hurt and might prevent a hard to identify bug later.Quoted 14 lines
rust/kernel/sync/locked_by.rs new file +14
-0+Self { + owner: owner.data.get (), + data:UnsafeCell ::new (data), + } + } +} + +impl <T : ?Sized ,U >LockedBy <T ,U > { +/// Returns a reference to the protected data when the caller provides evidence (via a +/// reference) that the owner is locked. +/// +/// `U` cannot be a zero-sized type (ZST) because there are ways to get an `&U` that matches +/// the data protected by the lock without actually holding it. +///
Quoted 8 lines
rust/kernel/sync/locked_by.rs line 114
Quoted 6 lines
rust/kernel/sync/locked_by.rs new file +6
-0+/// # Panics +/// +/// Panics if `owner` is different from the data protected by the lock used in +/// [`new`](LockedBy::new). +pub fn access <'a>(&'a self, owner: &'aU ) -> &'aT { +// Detect the usage of SZTs, which are supported, at compile time. Typos: "SZTs" -> "ZSTs" and "supported" -> "unsupported"? Also found below.
Oh, thanks for spotting these!
Quoted 7 lines
rust/kernel/sync/locked_by.rs line 115
Quoted 2 lines
rust/kernel/sync/locked_by.rs new file +1
-0+crate ::build_assert!(core::mem::size_of ::<U >() >0 );Could you add a meaningful error message here? Like "Cannot use
LockedBywhereUis a ZST, since it does not guarantee address uniqueness."
Also add this in the calls tobuild_assert!below and above.
I'm adding a message and removing the comment I had above in v4. Note, however, that this message isn't displayed when the build fails, so it is of limited use at the moment. (We do get a file name and line number, which helps bringing attention to the right place.)
Quoted 41 lines
--
Cheers,
BennoQuoted 35 lines
rust/kernel/sync/locked_by.rs new file +32
-1+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. +/// +/// `U` cannot be a zero-sized type (ZST) because there are ways to get an `&mut U` that +/// matches the data protected by the lock without actually holding it. +/// +/// Showing a mutable reference to the owner is sufficient because we know no other references +/// can exist to it. +/// +/// # Panics +/// +/// Panics if `owner` is different from the data protected by the lock used in +/// [`new`](LockedBy::new). +pub fn access_mut <'a>(&'a self, owner: &'amut U ) -> &'amut T { +// Detect the usage of SZTs, which are supported, at compile time. +crate ::build_assert!(core::mem::size_of ::<U >() >0 ); +if !ptr::eq (owner, self.owner) { +panic! ("mismatched owners" ); + } + +// SAFETY: `owner` is evidence that there is only one reference to the owner. +unsafe { &mut *self.data.get () } + } +} --2.34.1
Quoted 66 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.Cc Peter Zijlstra <[email protected]>Cc Ingo Molnar <[email protected]>Cc Will Deacon <[email protected]>Cc Waiman Long <[email protected]>Co-developed-by Boqun Feng <[email protected]>Signed-off-by Boqun Feng <[email protected]>Signed-off-by Wedson Almeida Filho <[email protected]>---
v1 -> v2: Fixed a typo in comment
v2 -> v3: Replacedcorewith::corein macrorust/kernel/sync.rs | 45 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+)rust/kernel/sync.rs +35
-0@@ -5,6 +5,51 @@//! This module contains the kernel APIs related to synchronisation that have been ported or //! wrapped for usage by Rust code in the kernel. +use crate ::types::Opaque ; +mod arc;pub use arc::{Arc ,ArcBorrow ,UniqueArc }; + +/// Represents a lockdep class. It's a wrapper around C's `lock_class_key`. +#[repr(transparent)] +pub struct LockClassKey (Opaque <bindings::lock_class_key >); + +// SAFETY: `bindings::lock_class_key` is designed to be used concurrently from multiple threads and +// provides its own synchronization. +unsafe impl Sync for LockClassKey {} + +impl LockClassKey { +/// Creates a new lock class key. +pub const fn new () ->Self { +Self (Opaque ::uninit ()) + } + +#[allow(dead_code)] +pub (crate )fn as_ptr (&self) -> *mut bindings::lock_class_key { + self.0 .get () + } +} + +/// Defines a new static lock class and returns a pointer to it. +#[doc(hidden)] +#[macro_export] +macro_rules! static_lock_class { + () => {{ +static CLASS : $crate::sync::LockClassKey = $crate::sync::LockClassKey ::new (); + &CLASS + }}; +} + +/// Returns the given string, if one is provided, otherwise generates one based on the source code +/// location.
rust/kernel/sync.rs line 55
Quoted 10 lines
rust/kernel/sync.rs +10
-0+#[doc(hidden)] +#[macro_export] +macro_rules! optional_name { + () => { + $crate::c_str!(::core::concat!(::core::file!(),":" , ::core::line!())) + }; + ($name:literal) => { + $crate::c_str!($name) + }; +}