kernel/sync/
lock.rs

1// SPDX-License-Identifier: GPL-2.0
2
3//! Generic kernel lock and guard.
4//!
5//! It contains a generic Rust lock and guard that allow for different backends (e.g., mutexes,
6//! spinlocks, raw spinlocks) to be provided with minimal effort.
7
8use super::LockClassKey;
9use crate::{
10    str::CStr,
11    types::{NotThreadSafe, Opaque, ScopeGuard},
12};
13use core::{cell::UnsafeCell, marker::PhantomPinned, pin::Pin};
14use pin_init::{pin_data, pin_init, PinInit};
15
16pub mod mutex;
17pub mod spinlock;
18
19pub(super) mod global;
20pub use global::{GlobalGuard, GlobalLock, GlobalLockBackend, GlobalLockedBy};
21
22/// The "backend" of a lock.
23///
24/// It is the actual implementation of the lock, without the need to repeat patterns used in all
25/// locks.
26///
27/// # Safety
28///
29/// - Implementers must ensure that only one thread/CPU may access the protected data once the lock
30///   is owned, that is, between calls to [`lock`] and [`unlock`].
31/// - Implementers must also ensure that [`relock`] uses the same locking method as the original
32///   lock operation.
33///
34/// [`lock`]: Backend::lock
35/// [`unlock`]: Backend::unlock
36/// [`relock`]: Backend::relock
37pub unsafe trait Backend {
38    /// The state required by the lock.
39    type State;
40
41    /// The state required to be kept between [`lock`] and [`unlock`].
42    ///
43    /// [`lock`]: Backend::lock
44    /// [`unlock`]: Backend::unlock
45    type GuardState;
46
47    /// Initialises the lock.
48    ///
49    /// # Safety
50    ///
51    /// `ptr` must be valid for write for the duration of the call, while `name` and `key` must
52    /// remain valid for read indefinitely.
53    unsafe fn init(
54        ptr: *mut Self::State,
55        name: *const crate::ffi::c_char,
56        key: *mut bindings::lock_class_key,
57    );
58
59    /// Acquires the lock, making the caller its owner.
60    ///
61    /// # Safety
62    ///
63    /// Callers must ensure that [`Backend::init`] has been previously called.
64    #[must_use]
65    unsafe fn lock(ptr: *mut Self::State) -> Self::GuardState;
66
67    /// Tries to acquire the lock.
68    ///
69    /// # Safety
70    ///
71    /// Callers must ensure that [`Backend::init`] has been previously called.
72    unsafe fn try_lock(ptr: *mut Self::State) -> Option<Self::GuardState>;
73
74    /// Releases the lock, giving up its ownership.
75    ///
76    /// # Safety
77    ///
78    /// It must only be called by the current owner of the lock.
79    unsafe fn unlock(ptr: *mut Self::State, guard_state: &Self::GuardState);
80
81    /// Reacquires the lock, making the caller its owner.
82    ///
83    /// # Safety
84    ///
85    /// Callers must ensure that `guard_state` comes from a previous call to [`Backend::lock`] (or
86    /// variant) that has been unlocked with [`Backend::unlock`] and will be relocked now.
87    unsafe fn relock(ptr: *mut Self::State, guard_state: &mut Self::GuardState) {
88        // SAFETY: The safety requirements ensure that the lock is initialised.
89        *guard_state = unsafe { Self::lock(ptr) };
90    }
91
92    /// Asserts that the lock is held using lockdep.
93    ///
94    /// # Safety
95    ///
96    /// Callers must ensure that [`Backend::init`] has been previously called.
97    unsafe fn assert_is_held(ptr: *mut Self::State);
98}
99
100/// A mutual exclusion primitive.
101///
102/// Exposes one of the kernel locking primitives. Which one is exposed depends on the lock
103/// [`Backend`] specified as the generic parameter `B`.
104#[repr(C)]
105#[pin_data]
106pub struct Lock<T: ?Sized, B: Backend> {
107    /// The kernel lock object.
108    #[pin]
109    state: Opaque<B::State>,
110
111    /// Some locks are known to be self-referential (e.g., mutexes), while others are architecture
112    /// or config defined (e.g., spinlocks). So we conservatively require them to be pinned in case
113    /// some architecture uses self-references now or in the future.
114    #[pin]
115    _pin: PhantomPinned,
116
117    /// The data protected by the lock.
118    pub(crate) data: UnsafeCell<T>,
119}
120
121// SAFETY: `Lock` can be transferred across thread boundaries iff the data it protects can.
122unsafe impl<T: ?Sized + Send, B: Backend> Send for Lock<T, B> {}
123
124// SAFETY: `Lock` serialises the interior mutability it provides, so it is `Sync` as long as the
125// data it protects is `Send`.
126unsafe impl<T: ?Sized + Send, B: Backend> Sync for Lock<T, B> {}
127
128impl<T, B: Backend> Lock<T, B> {
129    /// Constructs a new lock initialiser.
130    pub fn new(t: T, name: &'static CStr, key: Pin<&'static LockClassKey>) -> impl PinInit<Self> {
131        pin_init!(Self {
132            data: UnsafeCell::new(t),
133            _pin: PhantomPinned,
134            // SAFETY: `slot` is valid while the closure is called and both `name` and `key` have
135            // static lifetimes so they live indefinitely.
136            state <- Opaque::ffi_init(|slot| unsafe {
137                B::init(slot, name.as_char_ptr(), key.as_ptr())
138            }),
139        })
140    }
141}
142
143impl<B: Backend> Lock<(), B> {
144    /// Constructs a [`Lock`] from a raw pointer.
145    ///
146    /// This can be useful for interacting with a lock which was initialised outside of Rust.
147    ///
148    /// # Safety
149    ///
150    /// The caller promises that `ptr` points to a valid initialised instance of [`State`] during
151    /// the whole lifetime of `'a`.
152    ///
153    /// [`State`]: Backend::State
154    pub unsafe fn from_raw<'a>(ptr: *mut B::State) -> &'a Self {
155        // SAFETY:
156        // - By the safety contract `ptr` must point to a valid initialised instance of `B::State`
157        // - Since the lock data type is `()` which is a ZST, `state` is the only non-ZST member of
158        //   the struct
159        // - Combined with `#[repr(C)]`, this guarantees `Self` has an equivalent data layout to
160        //   `B::State`.
161        unsafe { &*ptr.cast() }
162    }
163}
164
165impl<T: ?Sized, B: Backend> Lock<T, B> {
166    /// Acquires the lock and gives the caller access to the data protected by it.
167    pub fn lock(&self) -> Guard<'_, T, B> {
168        // SAFETY: The constructor of the type calls `init`, so the existence of the object proves
169        // that `init` was called.
170        let state = unsafe { B::lock(self.state.get()) };
171        // SAFETY: The lock was just acquired.
172        unsafe { Guard::new(self, state) }
173    }
174
175    /// Tries to acquire the lock.
176    ///
177    /// Returns a guard that can be used to access the data protected by the lock if successful.
178    // `Option<T>` is not `#[must_use]` even if `T` is, thus the attribute is needed here.
179    #[must_use = "if unused, the lock will be immediately unlocked"]
180    pub fn try_lock(&self) -> Option<Guard<'_, T, B>> {
181        // SAFETY: The constructor of the type calls `init`, so the existence of the object proves
182        // that `init` was called.
183        unsafe { B::try_lock(self.state.get()).map(|state| Guard::new(self, state)) }
184    }
185}
186
187/// A lock guard.
188///
189/// Allows mutual exclusion primitives that implement the [`Backend`] trait to automatically unlock
190/// when a guard goes out of scope. It also provides a safe and convenient way to access the data
191/// protected by the lock.
192#[must_use = "the lock unlocks immediately when the guard is unused"]
193pub struct Guard<'a, T: ?Sized, B: Backend> {
194    pub(crate) lock: &'a Lock<T, B>,
195    pub(crate) state: B::GuardState,
196    _not_send: NotThreadSafe,
197}
198
199// SAFETY: `Guard` is sync when the data protected by the lock is also sync.
200unsafe impl<T: Sync + ?Sized, B: Backend> Sync for Guard<'_, T, B> {}
201
202impl<'a, T: ?Sized, B: Backend> Guard<'a, T, B> {
203    /// Returns the lock that this guard originates from.
204    ///
205    /// # Examples
206    ///
207    /// The following example shows how to use [`Guard::lock_ref()`] to assert the corresponding
208    /// lock is held.
209    ///
210    /// ```
211    /// # use kernel::{new_spinlock, sync::lock::{Backend, Guard, Lock}};
212    /// # use pin_init::stack_pin_init;
213    ///
214    /// fn assert_held<T, B: Backend>(guard: &Guard<'_, T, B>, lock: &Lock<T, B>) {
215    ///     // Address-equal means the same lock.
216    ///     assert!(core::ptr::eq(guard.lock_ref(), lock));
217    /// }
218    ///
219    /// // Creates a new lock on the stack.
220    /// stack_pin_init!{
221    ///     let l = new_spinlock!(42)
222    /// }
223    ///
224    /// let g = l.lock();
225    ///
226    /// // `g` originates from `l`.
227    /// assert_held(&g, &l);
228    /// ```
229    pub fn lock_ref(&self) -> &'a Lock<T, B> {
230        self.lock
231    }
232
233    pub(crate) fn do_unlocked<U>(&mut self, cb: impl FnOnce() -> U) -> U {
234        // SAFETY: The caller owns the lock, so it is safe to unlock it.
235        unsafe { B::unlock(self.lock.state.get(), &self.state) };
236
237        let _relock = ScopeGuard::new(||
238                // SAFETY: The lock was just unlocked above and is being relocked now.
239                unsafe { B::relock(self.lock.state.get(), &mut self.state) });
240
241        cb()
242    }
243}
244
245impl<T: ?Sized, B: Backend> core::ops::Deref for Guard<'_, T, B> {
246    type Target = T;
247
248    fn deref(&self) -> &Self::Target {
249        // SAFETY: The caller owns the lock, so it is safe to deref the protected data.
250        unsafe { &*self.lock.data.get() }
251    }
252}
253
254impl<T: ?Sized, B: Backend> core::ops::DerefMut for Guard<'_, T, B> {
255    fn deref_mut(&mut self) -> &mut Self::Target {
256        // SAFETY: The caller owns the lock, so it is safe to deref the protected data.
257        unsafe { &mut *self.lock.data.get() }
258    }
259}
260
261impl<T: ?Sized, B: Backend> Drop for Guard<'_, T, B> {
262    fn drop(&mut self) {
263        // SAFETY: The caller owns the lock, so it is safe to unlock it.
264        unsafe { B::unlock(self.lock.state.get(), &self.state) };
265    }
266}
267
268impl<'a, T: ?Sized, B: Backend> Guard<'a, T, B> {
269    /// Constructs a new immutable lock guard.
270    ///
271    /// # Safety
272    ///
273    /// The caller must ensure that it owns the lock.
274    pub unsafe fn new(lock: &'a Lock<T, B>, state: B::GuardState) -> Self {
275        // SAFETY: The caller can only hold the lock if `Backend::init` has already been called.
276        unsafe { B::assert_is_held(lock.state.get()) };
277
278        Self {
279            lock,
280            state,
281            _not_send: NotThreadSafe,
282        }
283    }
284}