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