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