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

This allows the definition of additional writable type states. Without
this patch, the `DerefMut` trait for guards is only implemented when the
type state is `WriteLock`; this is too restrictive for types that want
to implement more than one writable lock type state, for example, spin
locks that may have type states that have (or have not) disabled
interrupts.

This is in preparation for simplifying spinlocks, which comes in a
subsequent patch.

Signed-off-by: Wedson Almeida Filho <wedsonaf@google.com>

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 {}