Debian Codegraph @

rust/kernel/sync/lock/global.rs

raw
1 // SPDX-License-Identifier: GPL-2.0
2
3 // Copyright (C) 2024 Google LLC.
4
5 //! Support for defining statics containing locks.
6
7 use crate::{
8 str::{CStr, CStrExt as _},
9 sync::lock::{Backend, Guard, Lock},
10 sync::{LockClassKey, LockedBy},
11 types::Opaque,
12 };
13 use core::{
14 cell::UnsafeCell,
15 marker::{PhantomData, PhantomPinned},
16 pin::Pin,
17 };
18
19 /// Trait implemented for marker types for global locks.
20 ///
21 /// See [`global_lock!`] for examples.
22 pub trait GlobalLockBackend {
23 /// The name for this global lock.
24 const NAME: &'static CStr;
25 /// Item type stored in this global lock.
26 type Item: 'static;
27 /// The backend used for this global lock.
28 type Backend: Backend + 'static;
29 /// The class for this global lock.
30 fn get_lock_class() -> Pin<&'static LockClassKey>;
31 }
32
33 /// Type used for global locks.
34 ///
35 /// See [`global_lock!`] for examples.
36 pub struct GlobalLock<B: GlobalLockBackend> {
37 inner: Lock<B::Item, B::Backend>,
38 }
39
40 impl<B: GlobalLockBackend> GlobalLock<B> {
41 /// Creates a global lock.
42 ///
43 /// # Safety
44 ///
45 /// * Before any other method on this lock is called, [`Self::init`] must be called.
46 /// * The type `B` must not be used with any other lock.
47 pub const unsafe fn new(data: B::Item) -> Self {
48 Self {
49 inner: Lock {
50 state: Opaque::uninit(),
51 data: UnsafeCell::new(data),
52 _pin: PhantomPinned,
53 },
54 }
55 }
56
57 /// Initializes a global lock.
58 ///
59 /// # Safety
60 ///
61 /// Must not be called more than once on a given lock.
62 pub unsafe fn init(&'static self) {
63 // SAFETY: The pointer to `state` is valid for the duration of this call, and both `name`
64 // and `key` are valid indefinitely. The `state` is pinned since we have a `'static`
65 // reference to `self`.
66 //
67 // We have exclusive access to the `state` since the caller of `new` promised to call
68 // `init` before using any other methods. As `init` can only be called once, all other
69 // uses of this lock must happen after this call.
70 unsafe {
71 B::Backend::init(
72 self.inner.state.get(),
73 B::NAME.as_char_ptr(),
74 B::get_lock_class().as_ptr(),
75 )
76 }
77 }
78
79 /// Lock this global lock.
80 #[inline]
81 pub fn lock(&'static self) -> GlobalGuard<B> {
82 GlobalGuard {
83 inner: self.inner.lock(),
84 }
85 }
86
87 /// Try to lock this global lock.
88 #[inline]
89 pub fn try_lock(&'static self) -> Option<GlobalGuard<B>> {
90 Some(GlobalGuard {
91 inner: self.inner.try_lock()?,
92 })
93 }
94 }
95
96 /// A guard for a [`GlobalLock`].
97 ///
98 /// See [`global_lock!`] for examples.
99 pub struct GlobalGuard<B: GlobalLockBackend> {
100 inner: Guard<'static, B::Item, B::Backend>,
101 }
102
103 impl<B: GlobalLockBackend> core::ops::Deref for GlobalGuard<B> {
104 type Target = B::Item;
105
106 fn deref(&self) -> &Self::Target {
107 &self.inner
108 }
109 }
110
111 impl<B: GlobalLockBackend> core::ops::DerefMut for GlobalGuard<B>
112 where
113 B::Item: Unpin,
114 {
115 fn deref_mut(&mut self) -> &mut Self::Target {
116 &mut self.inner
117 }
118 }
119
120 /// A version of [`LockedBy`] for a [`GlobalLock`].
121 ///
122 /// See [`global_lock!`] for examples.
123 pub struct GlobalLockedBy<T: ?Sized, B: GlobalLockBackend> {
124 _backend: PhantomData<B>,
125 value: UnsafeCell<T>,
126 }
127
128 // SAFETY: The same thread-safety rules as `LockedBy` apply to `GlobalLockedBy`.
129 unsafe impl<T, B> Send for GlobalLockedBy<T, B>
130 where
131 T: ?Sized,
132 B: GlobalLockBackend,
133 LockedBy<T, B::Item>: Send,
134 {
135 }
136
137 // SAFETY: The same thread-safety rules as `LockedBy` apply to `GlobalLockedBy`.
138 unsafe impl<T, B> Sync for GlobalLockedBy<T, B>
139 where
140 T: ?Sized,
141 B: GlobalLockBackend,
142 LockedBy<T, B::Item>: Sync,
143 {
144 }
145
146 impl<T, B: GlobalLockBackend> GlobalLockedBy<T, B> {
147 /// Create a new [`GlobalLockedBy`].
148 ///
149 /// The provided value will be protected by the global lock indicated by `B`.
150 pub fn new(val: T) -> Self {
151 Self {
152 value: UnsafeCell::new(val),
153 _backend: PhantomData,
154 }
155 }
156 }
157
158 impl<T: ?Sized, B: GlobalLockBackend> GlobalLockedBy<T, B> {
159 /// Access the value immutably.
160 ///
161 /// The caller must prove shared access to the lock.
162 pub fn as_ref<'a>(&'a self, _guard: &'a GlobalGuard<B>) -> &'a T {
163 // SAFETY: The lock is globally unique, so there can only be one guard.
164 unsafe { &*self.value.get() }
165 }
166
167 /// Access the value mutably.
168 ///
169 /// The caller must prove shared exclusive to the lock.
170 pub fn as_mut<'a>(&'a self, _guard: &'a mut GlobalGuard<B>) -> &'a mut T {
171 // SAFETY: The lock is globally unique, so there can only be one guard.
172 unsafe { &mut *self.value.get() }
173 }
174
175 /// Access the value mutably directly.
176 ///
177 /// The caller has exclusive access to this `GlobalLockedBy`, so they do not need to hold the
178 /// lock.
179 pub fn get_mut(&mut self) -> &mut T {
180 self.value.get_mut()
181 }
182 }
183
184 /// Defines a global lock.
185 ///
186 /// The global mutex must be initialized before first use. Usually this is done by calling
187 /// [`GlobalLock::init`] in the module initializer.
188 ///
189 /// # Examples
190 ///
191 /// A global counter:
192 ///
193 /// ```
194 /// # mod ex {
195 /// # use kernel::prelude::*;
196 /// kernel::sync::global_lock! {
197 /// // SAFETY: Initialized in module initializer before first use.
198 /// unsafe(uninit) static MY_COUNTER: Mutex<u32> = 0;
199 /// }
200 ///
201 /// fn increment_counter() -> u32 {
202 /// let mut guard = MY_COUNTER.lock();
203 /// *guard += 1;
204 /// *guard
205 /// }
206 ///
207 /// impl kernel::Module for MyModule {
208 /// fn init(_module: &'static ThisModule) -> Result<Self> {
209 /// // SAFETY: Called exactly once.
210 /// unsafe { MY_COUNTER.init() };
211 ///
212 /// Ok(MyModule {})
213 /// }
214 /// }
215 /// # struct MyModule {}
216 /// # }
217 /// ```
218 ///
219 /// A global mutex used to protect all instances of a given struct:
220 ///
221 /// ```
222 /// # mod ex {
223 /// # use kernel::prelude::*;
224 /// use kernel::sync::{GlobalGuard, GlobalLockedBy};
225 ///
226 /// kernel::sync::global_lock! {
227 /// // SAFETY: Initialized in module initializer before first use.
228 /// unsafe(uninit) static MY_MUTEX: Mutex<()> = ();
229 /// }
230 ///
231 /// /// All instances of this struct are protected by `MY_MUTEX`.
232 /// struct MyStruct {
233 /// my_counter: GlobalLockedBy<u32, MY_MUTEX>,
234 /// }
235 ///
236 /// impl MyStruct {
237 /// /// Increment the counter in this instance.
238 /// ///
239 /// /// The caller must hold the `MY_MUTEX` mutex.
240 /// fn increment(&self, guard: &mut GlobalGuard<MY_MUTEX>) -> u32 {
241 /// let my_counter = self.my_counter.as_mut(guard);
242 /// *my_counter += 1;
243 /// *my_counter
244 /// }
245 /// }
246 ///
247 /// impl kernel::Module for MyModule {
248 /// fn init(_module: &'static ThisModule) -> Result<Self> {
249 /// // SAFETY: Called exactly once.
250 /// unsafe { MY_MUTEX.init() };
251 ///
252 /// Ok(MyModule {})
253 /// }
254 /// }
255 /// # struct MyModule {}
256 /// # }
257 /// ```
258 #[macro_export]
259 macro_rules! global_lock {
260 {
261 $(#[$meta:meta])* $pub:vis
262 unsafe(uninit) static $name:ident: $kind:ident<$valuety:ty> = $value:expr;
263 } => {
264 #[doc = ::core::concat!(
265 "Backend type used by [`",
266 ::core::stringify!($name),
267 "`](static@",
268 ::core::stringify!($name),
269 ")."
270 )]
271 #[allow(non_camel_case_types, unreachable_pub)]
272 $pub enum $name {}
273
274 impl $crate::sync::lock::GlobalLockBackend for $name {
275 const NAME: &'static $crate::str::CStr = $crate::c_str!(::core::stringify!($name));
276 type Item = $valuety;
277 type Backend = $crate::global_lock_inner!(backend $kind);
278
279 fn get_lock_class() -> Pin<&'static $crate::sync::LockClassKey> {
280 $crate::static_lock_class!()
281 }
282 }
283
284 $(#[$meta])*
285 $pub static $name: $crate::sync::lock::GlobalLock<$name> = {
286 // Defined here to be outside the unsafe scope.
287 let init: $valuety = $value;
288
289 // SAFETY:
290 // * The user of this macro promises to initialize the macro before use.
291 // * We are only generating one static with this backend type.
292 unsafe { $crate::sync::lock::GlobalLock::new(init) }
293 };
294 };
295 }
296 pub use global_lock;
297
298 #[doc(hidden)]
299 #[macro_export]
300 macro_rules! global_lock_inner {
301 (backend Mutex) => {
302 $crate::sync::lock::mutex::MutexBackend
303 };
304 (backend SpinLock) => {
305 $crate::sync::lock::spinlock::SpinLockBackend
306 };
307 }