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 aref; 14 pub mod atomic; 15 pub mod barrier; 16 pub mod completion; 17 mod condvar; 18 pub mod lock; 19 mod locked_by; 20 pub mod poll; 21 pub mod rcu; 22 mod refcount; 23 mod set_once; 24 25 pub use arc::{Arc, ArcBorrow, UniqueArc}; 26 pub use completion::Completion; 27 pub use condvar::{new_condvar, CondVar, CondVarTimeoutResult}; 28 pub use lock::global::{global_lock, GlobalGuard, GlobalLock, GlobalLockBackend, GlobalLockedBy}; 29 pub use lock::mutex::{new_mutex, Mutex, MutexGuard}; 30 pub use lock::spinlock::{new_spinlock, SpinLock, SpinLockGuard}; 31 pub use locked_by::LockedBy; 32 pub use refcount::Refcount; 33 pub use set_once::SetOnce; 34 35 /// Represents a lockdep class. 36 /// 37 /// Wraps the kernel's `struct lock_class_key`. 38 #[repr(transparent)] 39 #[pin_data(PinnedDrop)] 40 pub struct LockClassKey { 41 #[pin] 42 inner: Opaque<bindings::lock_class_key>, 43 } 44 45 // SAFETY: Unregistering a lock class key from a different thread than where it was registered is 46 // allowed. 47 unsafe impl Send for LockClassKey {} 48 49 // SAFETY: `bindings::lock_class_key` is designed to be used concurrently from multiple threads and 50 // provides its own synchronization. 51 unsafe impl Sync for LockClassKey {} 52 53 impl LockClassKey { 54 /// Initializes a statically allocated lock class key. 55 /// 56 /// This is usually used indirectly through the [`static_lock_class!`] macro. See its 57 /// documentation for more information. 58 /// 59 /// # Safety 60 /// 61 /// * Before using the returned value, it must be pinned in a static memory location. 62 /// * The destructor must never run on the returned `LockClassKey`. 63 pub const unsafe fn new_static() -> Self { 64 LockClassKey { 65 inner: Opaque::uninit(), 66 } 67 } 68 69 /// Initializes a dynamically allocated lock class key. 70 /// 71 /// In the common case of using a statically allocated lock class key, the 72 /// [`static_lock_class!`] macro should be used instead. 73 /// 74 /// # Examples 75 /// 76 /// ``` 77 /// use kernel::alloc::KBox; 78 /// use kernel::types::ForeignOwnable; 79 /// use kernel::sync::{LockClassKey, SpinLock}; 80 /// use pin_init::stack_pin_init; 81 /// 82 /// let key = KBox::pin_init(LockClassKey::new_dynamic(), GFP_KERNEL)?; 83 /// let key_ptr = key.into_foreign(); 84 /// 85 /// { 86 /// stack_pin_init!(let num: SpinLock<u32> = SpinLock::new( 87 /// 0, 88 /// c"my_spinlock", 89 /// // SAFETY: `key_ptr` is returned by the above `into_foreign()`, whose 90 /// // `from_foreign()` has not yet been called. 91 /// unsafe { <Pin<KBox<LockClassKey>> as ForeignOwnable>::borrow(key_ptr) } 92 /// )); 93 /// } 94 /// 95 /// // SAFETY: We dropped `num`, the only use of the key, so the result of the previous 96 /// // `borrow` has also been dropped. Thus, it's safe to use from_foreign. 97 /// unsafe { drop(<Pin<KBox<LockClassKey>> as ForeignOwnable>::from_foreign(key_ptr)) }; 98 /// # Ok::<(), Error>(()) 99 /// ``` 100 pub fn new_dynamic() -> impl PinInit<Self> { 101 pin_init!(Self { 102 // SAFETY: lockdep_register_key expects an uninitialized block of memory 103 inner <- Opaque::ffi_init(|slot| unsafe { bindings::lockdep_register_key(slot) }) 104 }) 105 } 106 107 /// Returns a raw pointer to the inner C struct. 108 /// 109 /// It is up to the caller to use the raw pointer correctly. 110 pub fn as_ptr(&self) -> *mut bindings::lock_class_key { 111 self.inner.get() 112 } 113 } 114 115 #[pinned_drop] 116 impl PinnedDrop for LockClassKey { 117 fn drop(self: Pin<&mut Self>) { 118 // SAFETY: `self.as_ptr()` was registered with lockdep and `self` is pinned, so the address 119 // hasn't changed. Thus, it's safe to pass it to unregister. 120 unsafe { bindings::lockdep_unregister_key(self.as_ptr()) } 121 } 122 } 123 124 /// Defines a new static lock class and returns a pointer to it. 125 /// 126 /// # Examples 127 /// 128 /// ``` 129 /// use kernel::sync::{static_lock_class, Arc, SpinLock}; 130 /// 131 /// fn new_locked_int() -> Result<Arc<SpinLock<u32>>> { 132 /// Arc::pin_init(SpinLock::new( 133 /// 42, 134 /// c"new_locked_int", 135 /// static_lock_class!(), 136 /// ), GFP_KERNEL) 137 /// } 138 /// ``` 139 #[macro_export] 140 macro_rules! static_lock_class { 141 () => {{ 142 static CLASS: $crate::sync::LockClassKey = 143 // SAFETY: The returned `LockClassKey` is stored in static memory and we pin it. Drop 144 // never runs on a static global. 145 unsafe { $crate::sync::LockClassKey::new_static() }; 146 $crate::prelude::Pin::static_ref(&CLASS) 147 }}; 148 } 149 pub use static_lock_class; 150 151 /// Returns the given string, if one is provided, otherwise generates one based on the source code 152 /// location. 153 #[doc(hidden)] 154 #[macro_export] 155 macro_rules! optional_name { 156 () => { 157 $crate::c_str!(::core::concat!(::core::file!(), ":", ::core::line!())) 158 }; 159 ($name:literal) => { 160 $crate::c_str!($name) 161 }; 162 } 163