xref: /linux/rust/kernel/sync.rs (revision 229f135e0680da3dd0bcce515c07be87858f1d12)
1 // SPDX-License-Identifier: GPL-2.0
2 
3 //! Synchronisation primitives.
4 //!
5 //! This module contains the kernel APIs related to synchronisation that have been ported or
6 //! wrapped for usage by Rust code in the kernel.
7 
8 use crate::prelude::*;
9 use crate::types::Opaque;
10 use pin_init;
11 
12 mod arc;
13 pub mod completion;
14 mod condvar;
15 pub mod lock;
16 mod locked_by;
17 pub mod poll;
18 pub mod rcu;
19 
20 pub use arc::{Arc, ArcBorrow, UniqueArc};
21 pub use completion::Completion;
22 pub use condvar::{new_condvar, CondVar, CondVarTimeoutResult};
23 pub use lock::global::{global_lock, GlobalGuard, GlobalLock, GlobalLockBackend, GlobalLockedBy};
24 pub use lock::mutex::{new_mutex, Mutex, MutexGuard};
25 pub use lock::spinlock::{new_spinlock, SpinLock, SpinLockGuard};
26 pub use locked_by::LockedBy;
27 
28 /// Represents a lockdep class. It's a wrapper around C's `lock_class_key`.
29 #[repr(transparent)]
30 #[pin_data(PinnedDrop)]
31 pub struct LockClassKey {
32     #[pin]
33     inner: Opaque<bindings::lock_class_key>,
34 }
35 
36 // SAFETY: `bindings::lock_class_key` is designed to be used concurrently from multiple threads and
37 // provides its own synchronization.
38 unsafe impl Sync for LockClassKey {}
39 
40 impl LockClassKey {
41     /// Initializes a dynamically allocated lock class key. In the common case of using a
42     /// statically allocated lock class key, the static_lock_class! macro should be used instead.
43     ///
44     /// # Example
45     /// ```
46     /// # use kernel::c_str;
47     /// # use kernel::alloc::KBox;
48     /// # use kernel::types::ForeignOwnable;
49     /// # use kernel::sync::{LockClassKey, SpinLock};
50     /// # use pin_init::stack_pin_init;
51     ///
52     /// let key = KBox::pin_init(LockClassKey::new_dynamic(), GFP_KERNEL)?;
53     /// let key_ptr = key.into_foreign();
54     ///
55     /// {
56     ///     stack_pin_init!(let num: SpinLock<u32> = SpinLock::new(
57     ///         0,
58     ///         c_str!("my_spinlock"),
59     ///         // SAFETY: `key_ptr` is returned by the above `into_foreign()`, whose
60     ///         // `from_foreign()` has not yet been called.
61     ///         unsafe { <Pin<KBox<LockClassKey>> as ForeignOwnable>::borrow(key_ptr) }
62     ///     ));
63     /// }
64     ///
65     /// // SAFETY: We dropped `num`, the only use of the key, so the result of the previous
66     /// // `borrow` has also been dropped. Thus, it's safe to use from_foreign.
67     /// unsafe { drop(<Pin<KBox<LockClassKey>> as ForeignOwnable>::from_foreign(key_ptr)) };
68     ///
69     /// # Ok::<(), Error>(())
70     /// ```
new_dynamic() -> impl PinInit<Self>71     pub fn new_dynamic() -> impl PinInit<Self> {
72         pin_init!(Self {
73             // SAFETY: lockdep_register_key expects an uninitialized block of memory
74             inner <- Opaque::ffi_init(|slot| unsafe { bindings::lockdep_register_key(slot) })
75         })
76     }
77 
as_ptr(&self) -> *mut bindings::lock_class_key78     pub(crate) fn as_ptr(&self) -> *mut bindings::lock_class_key {
79         self.inner.get()
80     }
81 }
82 
83 #[pinned_drop]
84 impl PinnedDrop for LockClassKey {
drop(self: Pin<&mut Self>)85     fn drop(self: Pin<&mut Self>) {
86         // SAFETY: self.as_ptr was registered with lockdep and self is pinned, so the address
87         // hasn't changed. Thus, it's safe to pass to unregister.
88         unsafe { bindings::lockdep_unregister_key(self.as_ptr()) }
89     }
90 }
91 
92 /// Defines a new static lock class and returns a pointer to it.
93 #[doc(hidden)]
94 #[macro_export]
95 macro_rules! static_lock_class {
96     () => {{
97         static CLASS: $crate::sync::LockClassKey =
98             // SAFETY: lockdep expects uninitialized memory when it's handed a statically allocated
99             // lock_class_key
100             unsafe { ::core::mem::MaybeUninit::uninit().assume_init() };
101         $crate::prelude::Pin::static_ref(&CLASS)
102     }};
103 }
104 
105 /// Returns the given string, if one is provided, otherwise generates one based on the source code
106 /// location.
107 #[doc(hidden)]
108 #[macro_export]
109 macro_rules! optional_name {
110     () => {
111         $crate::c_str!(::core::concat!(::core::file!(), ":", ::core::line!()))
112     };
113     ($name:literal) => {
114         $crate::c_str!($name)
115     };
116 }
117