1 // SPDX-License-Identifier: GPL-2.0 2 3 //! A condition variable. 4 //! 5 //! This module allows Rust code to use the kernel's [`struct wait_queue_head`] as a condition 6 //! variable. 7 8 use super::{lock::Backend, lock::Guard, LockClassKey}; 9 use crate::{ 10 ffi::{c_int, c_long}, 11 init::PinInit, 12 pin_init, 13 str::CStr, 14 task::{MAX_SCHEDULE_TIMEOUT, TASK_INTERRUPTIBLE, TASK_NORMAL, TASK_UNINTERRUPTIBLE}, 15 time::Jiffies, 16 types::Opaque, 17 }; 18 use core::marker::PhantomPinned; 19 use core::ptr; 20 use macros::pin_data; 21 22 /// Creates a [`CondVar`] initialiser with the given name and a newly-created lock class. 23 #[macro_export] 24 macro_rules! new_condvar { 25 ($($name:literal)?) => { 26 $crate::sync::CondVar::new($crate::optional_name!($($name)?), $crate::static_lock_class!()) 27 }; 28 } 29 pub use new_condvar; 30 31 /// A conditional variable. 32 /// 33 /// Exposes the kernel's [`struct wait_queue_head`] as a condition variable. It allows the caller to 34 /// atomically release the given lock and go to sleep. It reacquires the lock when it wakes up. And 35 /// it wakes up when notified by another thread (via [`CondVar::notify_one`] or 36 /// [`CondVar::notify_all`]) or because the thread received a signal. It may also wake up 37 /// spuriously. 38 /// 39 /// Instances of [`CondVar`] need a lock class and to be pinned. The recommended way to create such 40 /// instances is with the [`pin_init`](crate::pin_init) and [`new_condvar`] macros. 41 /// 42 /// # Examples 43 /// 44 /// The following is an example of using a condvar with a mutex: 45 /// 46 /// ``` 47 /// use kernel::sync::{new_condvar, new_mutex, CondVar, Mutex}; 48 /// 49 /// #[pin_data] 50 /// pub struct Example { 51 /// #[pin] 52 /// value: Mutex<u32>, 53 /// 54 /// #[pin] 55 /// value_changed: CondVar, 56 /// } 57 /// 58 /// /// Waits for `e.value` to become `v`. 59 /// fn wait_for_value(e: &Example, v: u32) { 60 /// let mut guard = e.value.lock(); 61 /// while *guard != v { 62 /// e.value_changed.wait(&mut guard); 63 /// } 64 /// } 65 /// 66 /// /// Increments `e.value` and notifies all potential waiters. 67 /// fn increment(e: &Example) { 68 /// *e.value.lock() += 1; 69 /// e.value_changed.notify_all(); 70 /// } 71 /// 72 /// /// Allocates a new boxed `Example`. 73 /// fn new_example() -> Result<Pin<KBox<Example>>> { 74 /// KBox::pin_init(pin_init!(Example { 75 /// value <- new_mutex!(0), 76 /// value_changed <- new_condvar!(), 77 /// }), GFP_KERNEL) 78 /// } 79 /// ``` 80 /// 81 /// [`struct wait_queue_head`]: srctree/include/linux/wait.h 82 #[pin_data] 83 pub struct CondVar { 84 #[pin] 85 pub(crate) wait_queue_head: Opaque<bindings::wait_queue_head>, 86 87 /// A condvar needs to be pinned because it contains a [`struct list_head`] that is 88 /// self-referential, so it cannot be safely moved once it is initialised. 89 /// 90 /// [`struct list_head`]: srctree/include/linux/types.h 91 #[pin] 92 _pin: PhantomPinned, 93 } 94 95 // SAFETY: `CondVar` only uses a `struct wait_queue_head`, which is safe to use on any thread. 96 unsafe impl Send for CondVar {} 97 98 // SAFETY: `CondVar` only uses a `struct wait_queue_head`, which is safe to use on multiple threads 99 // concurrently. 100 unsafe impl Sync for CondVar {} 101 102 impl CondVar { 103 /// Constructs a new condvar initialiser. 104 pub fn new(name: &'static CStr, key: &'static LockClassKey) -> impl PinInit<Self> { 105 pin_init!(Self { 106 _pin: PhantomPinned, 107 // SAFETY: `slot` is valid while the closure is called and both `name` and `key` have 108 // static lifetimes so they live indefinitely. 109 wait_queue_head <- Opaque::ffi_init(|slot| unsafe { 110 bindings::__init_waitqueue_head(slot, name.as_char_ptr(), key.as_ptr()) 111 }), 112 }) 113 } 114 115 fn wait_internal<T: ?Sized, B: Backend>( 116 &self, 117 wait_state: c_int, 118 guard: &mut Guard<'_, T, B>, 119 timeout_in_jiffies: c_long, 120 ) -> c_long { 121 let wait = Opaque::<bindings::wait_queue_entry>::uninit(); 122 123 // SAFETY: `wait` points to valid memory. 124 unsafe { bindings::init_wait(wait.get()) }; 125 126 // SAFETY: Both `wait` and `wait_queue_head` point to valid memory. 127 unsafe { 128 bindings::prepare_to_wait_exclusive(self.wait_queue_head.get(), wait.get(), wait_state) 129 }; 130 131 // SAFETY: Switches to another thread. The timeout can be any number. 132 let ret = guard.do_unlocked(|| unsafe { bindings::schedule_timeout(timeout_in_jiffies) }); 133 134 // SAFETY: Both `wait` and `wait_queue_head` point to valid memory. 135 unsafe { bindings::finish_wait(self.wait_queue_head.get(), wait.get()) }; 136 137 ret 138 } 139 140 /// Releases the lock and waits for a notification in uninterruptible mode. 141 /// 142 /// Atomically releases the given lock (whose ownership is proven by the guard) and puts the 143 /// thread to sleep, reacquiring the lock on wake up. It wakes up when notified by 144 /// [`CondVar::notify_one`] or [`CondVar::notify_all`]. Note that it may also wake up 145 /// spuriously. 146 pub fn wait<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) { 147 self.wait_internal(TASK_UNINTERRUPTIBLE, guard, MAX_SCHEDULE_TIMEOUT); 148 } 149 150 /// Releases the lock and waits for a notification in interruptible mode. 151 /// 152 /// Similar to [`CondVar::wait`], except that the wait is interruptible. That is, the thread may 153 /// wake up due to signals. It may also wake up spuriously. 154 /// 155 /// Returns whether there is a signal pending. 156 #[must_use = "wait_interruptible returns if a signal is pending, so the caller must check the return value"] 157 pub fn wait_interruptible<T: ?Sized, B: Backend>(&self, guard: &mut Guard<'_, T, B>) -> bool { 158 self.wait_internal(TASK_INTERRUPTIBLE, guard, MAX_SCHEDULE_TIMEOUT); 159 crate::current!().signal_pending() 160 } 161 162 /// Releases the lock and waits for a notification in interruptible mode. 163 /// 164 /// Atomically releases the given lock (whose ownership is proven by the guard) and puts the 165 /// thread to sleep. It wakes up when notified by [`CondVar::notify_one`] or 166 /// [`CondVar::notify_all`], or when a timeout occurs, or when the thread receives a signal. 167 #[must_use = "wait_interruptible_timeout returns if a signal is pending, so the caller must check the return value"] 168 pub fn wait_interruptible_timeout<T: ?Sized, B: Backend>( 169 &self, 170 guard: &mut Guard<'_, T, B>, 171 jiffies: Jiffies, 172 ) -> CondVarTimeoutResult { 173 let jiffies = jiffies.try_into().unwrap_or(MAX_SCHEDULE_TIMEOUT); 174 let res = self.wait_internal(TASK_INTERRUPTIBLE, guard, jiffies); 175 176 match (res as Jiffies, crate::current!().signal_pending()) { 177 (jiffies, true) => CondVarTimeoutResult::Signal { jiffies }, 178 (0, false) => CondVarTimeoutResult::Timeout, 179 (jiffies, false) => CondVarTimeoutResult::Woken { jiffies }, 180 } 181 } 182 183 /// Calls the kernel function to notify the appropriate number of threads. 184 fn notify(&self, count: c_int) { 185 // SAFETY: `wait_queue_head` points to valid memory. 186 unsafe { 187 bindings::__wake_up( 188 self.wait_queue_head.get(), 189 TASK_NORMAL, 190 count, 191 ptr::null_mut(), 192 ) 193 }; 194 } 195 196 /// Calls the kernel function to notify one thread synchronously. 197 /// 198 /// This method behaves like `notify_one`, except that it hints to the scheduler that the 199 /// current thread is about to go to sleep, so it should schedule the target thread on the same 200 /// CPU. 201 pub fn notify_sync(&self) { 202 // SAFETY: `wait_queue_head` points to valid memory. 203 unsafe { bindings::__wake_up_sync(self.wait_queue_head.get(), TASK_NORMAL) }; 204 } 205 206 /// Wakes a single waiter up, if any. 207 /// 208 /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost 209 /// completely (as opposed to automatically waking up the next waiter). 210 pub fn notify_one(&self) { 211 self.notify(1); 212 } 213 214 /// Wakes all waiters up, if any. 215 /// 216 /// This is not 'sticky' in the sense that if no thread is waiting, the notification is lost 217 /// completely (as opposed to automatically waking up the next waiter). 218 pub fn notify_all(&self) { 219 self.notify(0); 220 } 221 } 222 223 /// The return type of `wait_timeout`. 224 pub enum CondVarTimeoutResult { 225 /// The timeout was reached. 226 Timeout, 227 /// Somebody woke us up. 228 Woken { 229 /// Remaining sleep duration. 230 jiffies: Jiffies, 231 }, 232 /// A signal occurred. 233 Signal { 234 /// Remaining sleep duration. 235 jiffies: Jiffies, 236 }, 237 } 238