Merge pull request #679 from wedsonaf/lock-info

rust: define `LockInfo` trait that lock "type states" must implement

Author: wedsonaf

rust/kernel/lib.rs

@@ -96,7 +96,7 @@ pub mod user_ptr;
 pub use build_error::build_error;
 
 pub use crate::error::{to_result, Error, Result};
-pub use crate::types::{bit, bits_iter, Mode, Opaque, ScopeGuard};
+pub use crate::types::{bit, bits_iter, Bool, False, Mode, Opaque, ScopeGuard, True};
 
 use core::marker::PhantomData;
 

rust/kernel/sync/condvar.rs

@@ -5,7 +5,7 @@
 //! This module allows Rust code to use the kernel's [`struct wait_queue_head`] as a condition
 //! variable.
 
-use super::{Guard, Lock, NeedsLockClass};
+use super::{Guard, Lock, LockInfo, NeedsLockClass};
 use crate::{bindings, str::CStr, task::Task, Opaque};
 use core::{marker::PhantomPinned, pin::Pin};
 
@@ -61,7 +61,7 @@ impl CondVar {
     ///
     /// 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<L: Lock<M>, M>(&self, guard: &mut Guard<'_, L, M>) -> bool {
+    pub fn wait<L: Lock<I>, I: LockInfo>(&self, guard: &mut Guard<'_, L, I>) -> bool {
         let lock = guard.lock;
         let wait = Opaque::<bindings::wait_queue_entry>::uninit();
 

rust/kernel/sync/guard.rs

@@ -7,14 +7,14 @@
 //! other constructs to work on generic locking primitives.
 
 use super::NeedsLockClass;
-use crate::{bindings, str::CStr};
+use crate::{bindings, str::CStr, Bool, False, True};
 use core::pin::Pin;
 
 /// Allows mutual exclusion primitives that implement the [`Lock`] 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, L: Lock<M> + ?Sized, M = WriteLock> {
+pub struct Guard<'a, L: Lock<I> + ?Sized, I: LockInfo = WriteLock> {
     pub(crate) lock: &'a L,
     pub(crate) context: L::GuardContext,
 }
@@ -23,14 +23,15 @@ pub struct Guard<'a, L: Lock<M> + ?Sized, M = WriteLock> {
 // conservative than the default compiler implementation; more details can be found on
 // https://github.com/rust-lang/rust/issues/41622 -- it refers to `MutexGuard` from the standard
 // library.
-unsafe impl<L, M> Sync for Guard<'_, L, M>
+unsafe impl<L, I> Sync for Guard<'_, L, I>
 where
-    L: Lock<M> + ?Sized,
+    L: Lock<I> + ?Sized,
     L::Inner: Sync,
+    I: LockInfo,
 {
 }
 
-impl<L: Lock<M> + ?Sized, M> core::ops::Deref for Guard<'_, L, M> {
+impl<L: Lock<I> + ?Sized, I: LockInfo> core::ops::Deref for Guard<'_, L, I> {
     type Target = L::Inner;
 
     fn deref(&self) -> &Self::Target {
@@ -39,21 +40,21 @@ impl<L: Lock<M> + ?Sized, M> core::ops::Deref for Guard<'_, L, M> {
     }
 }
 
-impl<L: Lock<WriteLock> + ?Sized> core::ops::DerefMut for Guard<'_, L, WriteLock> {
+impl<L: Lock<I> + ?Sized, I: LockInfo<Writable = True>> core::ops::DerefMut for Guard<'_, L, I> {
     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.locked_data().get() }
     }
 }
 
-impl<L: Lock<M> + ?Sized, M> Drop for Guard<'_, L, M> {
+impl<L: Lock<I> + ?Sized, I: LockInfo> Drop for Guard<'_, L, I> {
     fn drop(&mut self) {
         // SAFETY: The caller owns the lock, so it is safe to unlock it.
         unsafe { self.lock.unlock(&mut self.context) };
     }
 }
 
-impl<'a, L: Lock<M> + ?Sized, M> Guard<'a, L, M> {
+impl<'a, L: Lock<I> + ?Sized, I: LockInfo> Guard<'a, L, I> {
     /// Constructs a new immutable lock guard.
     ///
     /// # Safety
@@ -64,11 +65,23 @@ impl<'a, L: Lock<M> + ?Sized, M> Guard<'a, L, M> {
     }
 }
 
+/// Specifies properties of a lock.
+pub trait LockInfo {
+    /// Determines if the data protected by a lock is writable.
+    type Writable: Bool;
+}
+
 /// A marker for locks that only allow reading.
 pub struct ReadLock;
+impl LockInfo for ReadLock {
+    type Writable = False;
+}
 
 /// A marker for locks that allow reading and writing.
 pub struct WriteLock;
+impl LockInfo for WriteLock {
+    type Writable = True;
+}
 
 /// A generic mutual exclusion primitive.
 ///
@@ -83,7 +96,7 @@ pub struct WriteLock;
 /// - Implementers of all other markers must ensure that a mutable reference to the protected data
 ///   is not active in any thread/CPU because at least one shared refence is active between calls
 ///   to `lock_noguard` and `unlock`.
-pub unsafe trait Lock<M = WriteLock> {
+pub unsafe trait Lock<I: LockInfo = WriteLock> {
     /// The type of the data protected by the lock.
     type Inner: ?Sized;
 
@@ -116,13 +129,16 @@ pub unsafe trait Lock<M = WriteLock> {
 }
 
 /// A generic mutual exclusion primitive that can be instantiated generically.
-pub trait CreatableLock<M = WriteLock>: Lock<M> {
+pub trait CreatableLock {
+    /// The type of the argument passed to [`CreatableLock::new_lock`].
+    type CreateArgType: ?Sized;
+
     /// Constructs a new instance of the lock.
     ///
     /// # Safety
     ///
     /// The caller must call [`CreatableLock::init_lock`] before using the lock.
-    unsafe fn new_lock(data: Self::Inner) -> Self;
+    unsafe fn new_lock(data: Self::CreateArgType) -> Self;
 
     /// Initialises the lock type instance so that it can be safely used.
     ///

rust/kernel/sync/mod.rs

@@ -35,7 +35,7 @@ mod spinlock;
 
 pub use arc::{Ref, RefBorrow, UniqueRef};
 pub use condvar::CondVar;
-pub use guard::{CreatableLock, Guard, Lock, ReadLock, WriteLock};
+pub use guard::{CreatableLock, Guard, Lock, LockInfo, ReadLock, WriteLock};
 pub use locked_by::LockedBy;
 pub use mutex::Mutex;
 pub use revocable_mutex::{RevocableMutex, RevocableMutexGuard};

rust/kernel/sync/mutex.rs

@@ -73,7 +73,9 @@ impl<T: ?Sized> Mutex<T> {
 }
 
 impl<T> CreatableLock for Mutex<T> {
-    unsafe fn new_lock(data: Self::Inner) -> Self {
+    type CreateArgType = T;
+
+    unsafe fn new_lock(data: Self::CreateArgType) -> Self {
         // SAFETY: The safety requirements of `new_lock` also require that `init_lock` be called.
         unsafe { Self::new(data) }
     }

rust/kernel/sync/rwsem.rs

@@ -86,7 +86,9 @@ impl<T: ?Sized> RwSemaphore<T> {
 }
 
 impl<T> CreatableLock for RwSemaphore<T> {
-    unsafe fn new_lock(data: Self::Inner) -> Self {
+    type CreateArgType = T;
+
+    unsafe fn new_lock(data: Self::CreateArgType) -> Self {
         // SAFETY: The safety requirements of `new_lock` also require that `init_lock` be called.
         unsafe { Self::new(data) }
     }

rust/kernel/sync/seqlock.rs

@@ -52,7 +52,7 @@ use core::{cell::UnsafeCell, marker::PhantomPinned, ops::Deref, pin::Pin};
 ///     guard.b.store(b + 1, Ordering::Relaxed);
 /// }
 /// ```
-pub struct SeqLock<L: CreatableLock + ?Sized> {
+pub struct SeqLock<L: CreatableLock + Lock + ?Sized> {
     _p: PhantomPinned,
     count: Opaque<bindings::seqcount>,
     write_lock: L,
@@ -61,21 +61,21 @@ pub struct SeqLock<L: CreatableLock + ?Sized> {
 // SAFETY: `SeqLock` can be transferred across thread boundaries iff the data it protects and the
 // underlying lock can.
 #[allow(clippy::non_send_fields_in_send_ty)]
-unsafe impl<L: CreatableLock + Send> Send for SeqLock<L> where L::Inner: Send {}
+unsafe impl<L: CreatableLock + Lock + Send> Send for SeqLock<L> where L::Inner: Send {}
 
 // SAFETY: `SeqLock` allows concurrent access to the data it protects by both readers and writers,
 // so it requires that the data it protects be `Sync`, as well as the underlying lock.
-unsafe impl<L: CreatableLock + Sync> Sync for SeqLock<L> where L::Inner: Sync {}
+unsafe impl<L: CreatableLock + Lock + Sync> Sync for SeqLock<L> where L::Inner: Sync {}
 
-impl<L: CreatableLock> SeqLock<L> {
+impl<L: CreatableLock + Lock> SeqLock<L> {
     /// Constructs a new instance of [`SeqLock`].
     ///
     /// # Safety
     ///
     /// The caller must call [`SeqLock::init`] before using the seqlock.
-    pub unsafe fn new(data: L::Inner) -> Self
+    pub unsafe fn new(data: L::CreateArgType) -> Self
     where
-        L::Inner: Sized,
+        L::CreateArgType: Sized,
     {
         Self {
             _p: PhantomPinned,
@@ -87,7 +87,7 @@ impl<L: CreatableLock> SeqLock<L> {
     }
 }
 
-impl<L: CreatableLock + ?Sized> SeqLock<L> {
+impl<L: CreatableLock + Lock + ?Sized> SeqLock<L> {
     /// Accesses the protected data in read mode.
     ///
     /// Readers and writers are allowed to run concurrently, so callers must check if they need to
@@ -129,7 +129,7 @@ impl<L: CreatableLock + ?Sized> SeqLock<L> {
     }
 }
 
-impl<L: CreatableLock + ?Sized> NeedsLockClass for SeqLock<L> {
+impl<L: CreatableLock + Lock + ?Sized> NeedsLockClass for SeqLock<L> {
     unsafe fn init(
         mut self: Pin<&mut Self>,
         name: &'static CStr,
@@ -146,7 +146,7 @@ impl<L: CreatableLock + ?Sized> NeedsLockClass for SeqLock<L> {
 }
 
 // SAFETY: The underlying lock ensures mutual exclusion.
-unsafe impl<L: CreatableLock + ?Sized> Lock<ReadLock> for SeqLock<L> {
+unsafe impl<L: CreatableLock + Lock + ?Sized> Lock<ReadLock> for SeqLock<L> {
     type Inner = L::Inner;
     type GuardContext = L::GuardContext;
 
@@ -176,12 +176,12 @@ unsafe impl<L: CreatableLock + ?Sized> Lock<ReadLock> for SeqLock<L> {
 }
 
 /// Allows read-side access to data protected by a sequential lock.
-pub struct SeqLockReadGuard<'a, L: CreatableLock + ?Sized> {
+pub struct SeqLockReadGuard<'a, L: CreatableLock + Lock + ?Sized> {
     lock: &'a SeqLock<L>,
     start_count: u32,
 }
 
-impl<L: CreatableLock + ?Sized> SeqLockReadGuard<'_, L> {
+impl<L: CreatableLock + Lock + ?Sized> SeqLockReadGuard<'_, L> {
     /// Determine if the callers needs to retry reading values.
     ///
     /// It returns `true` when a concurrent writer ran between the guard being created and
@@ -192,7 +192,7 @@ impl<L: CreatableLock + ?Sized> SeqLockReadGuard<'_, L> {
     }
 }
 
-impl<L: CreatableLock + ?Sized> Deref for SeqLockReadGuard<'_, L> {
+impl<L: CreatableLock + Lock + ?Sized> Deref for SeqLockReadGuard<'_, L> {
     type Target = L::Inner;
 
     fn deref(&self) -> &Self::Target {

rust/kernel/sync/spinlock.rs

@@ -131,7 +131,9 @@ impl<T: ?Sized> SpinLock<T> {
 }
 
 impl<T> CreatableLock for SpinLock<T> {
-    unsafe fn new_lock(data: Self::Inner) -> Self {
+    type CreateArgType = T;
+
+    unsafe fn new_lock(data: Self::CreateArgType) -> Self {
         // SAFETY: The safety requirements of `new_lock` also require that `init_lock` be called.
         unsafe { Self::new(data) }
     }

rust/kernel/types.rs

@@ -484,3 +484,86 @@ where
 
     BitIterator { value }
 }
+
+/// A trait for boolean types.
+///
+/// This is meant to be used in type states to allow booelan constraints in implementation blocks.
+/// In the example below, the implementation containing `MyType::set_value` could _not_ be
+/// constrained to type states containing `Writable = true` if `Writable` were a constant instead
+/// of a type.
+///
+/// # Safety
+///
+/// No additional implementations of [`Bool`] should be provided, as [`True`] and [`False`] are
+/// already provided.
+///
+/// # Examples
+///
+/// ```
+/// # use kernel::{Bool, False, True};
+/// use core::marker::PhantomData;
+///
+/// // Type state specifies whether the type is writable.
+/// trait MyTypeState {
+///     type Writable: Bool;
+/// }
+///
+/// // In state S1, the type is writable.
+/// struct S1;
+/// impl MyTypeState for S1 {
+///     type Writable = True;
+/// }
+///
+/// // In state S2, the type is not writable.
+/// struct S2;
+/// impl MyTypeState for S2 {
+///     type Writable = False;
+/// }
+///
+/// struct MyType<T: MyTypeState> {
+///     value: u32,
+///     _p: PhantomData<T>,
+/// }
+///
+/// impl<T: MyTypeState> MyType<T> {
+///     fn new(value: u32) -> Self {
+///         Self {
+///             value,
+///             _p: PhantomData,
+///         }
+///     }
+/// }
+///
+/// // This implementation block only applies if the type state is writable.
+/// impl<T> MyType<T>
+/// where
+///     T: MyTypeState<Writable = True>,
+/// {
+///     fn set_value(&mut self, v: u32) {
+///         self.value = v;
+///     }
+/// }
+///
+/// pub(crate) fn test() {
+///     let mut x = MyType::<S1>::new(10);
+///     let mut y = MyType::<S2>::new(20);
+///
+///     x.set_value(30);
+///
+///     // The code below fails to compile because `S2` is not writable.
+///     // y.set_value(40);
+/// }
+/// ```
+pub unsafe trait Bool {}
+
+/// Represents the `true` value for types with [`Bool`] bound.
+pub struct True;
+
+// SAFETY: This is one of the only two implementations of `Bool`.
+unsafe impl Bool for True {}
+
+/// Represents the `false` value for types wth [`Bool`] bound.
+pub struct False;
+
+// SAFETY: This is one of the only two implementations of `Bool`.
+unsafe impl Bool for False {}