kernel/sync/poll.rs
1// SPDX-License-Identifier: GPL-2.0
2
3// Copyright (C) 2024 Google LLC.
4
5//! Utilities for working with `struct poll_table`.
6
7use crate::{
8 bindings,
9 fs::File,
10 prelude::*,
11 sync::{CondVar, LockClassKey},
12};
13use core::{marker::PhantomData, ops::Deref};
14
15/// Creates a [`PollCondVar`] initialiser with the given name and a newly-created lock class.
16#[macro_export]
17macro_rules! new_poll_condvar {
18 ($($name:literal)?) => {
19 $crate::sync::poll::PollCondVar::new(
20 $crate::optional_name!($($name)?), $crate::static_lock_class!()
21 )
22 };
23}
24
25/// Wraps the kernel's `poll_table`.
26///
27/// # Invariants
28///
29/// The pointer must be null or reference a valid `poll_table`.
30#[repr(transparent)]
31pub struct PollTable<'a> {
32 table: *mut bindings::poll_table,
33 _lifetime: PhantomData<&'a bindings::poll_table>,
34}
35
36impl<'a> PollTable<'a> {
37 /// Creates a [`PollTable`] from a valid pointer.
38 ///
39 /// # Safety
40 ///
41 /// The pointer must be null or reference a valid `poll_table` for the duration of `'a`.
42 pub unsafe fn from_raw(table: *mut bindings::poll_table) -> Self {
43 // INVARIANTS: The safety requirements are the same as the struct invariants.
44 PollTable {
45 table,
46 _lifetime: PhantomData,
47 }
48 }
49
50 /// Register this [`PollTable`] with the provided [`PollCondVar`], so that it can be notified
51 /// using the condition variable.
52 pub fn register_wait(&self, file: &File, cv: &PollCondVar) {
53 // SAFETY: The pointers `self.table` and `file` are valid for the duration of this call.
54 // The `cv.wait_queue_head` pointer must be valid until an rcu grace period after the
55 // waiter is removed. The `PollCondVar` is pinned, so before `cv.wait_queue_head` can be
56 // destroyed, the destructor must run. That destructor first removes all waiters, and then
57 // waits for an rcu grace period. Therefore, `cv.wait_queue_head` is valid for long enough.
58 unsafe { bindings::poll_wait(file.as_ptr(), cv.wait_queue_head.get(), self.table) }
59 }
60}
61
62/// A wrapper around [`CondVar`] that makes it usable with [`PollTable`].
63///
64/// [`CondVar`]: crate::sync::CondVar
65#[pin_data(PinnedDrop)]
66pub struct PollCondVar {
67 #[pin]
68 inner: CondVar,
69}
70
71impl PollCondVar {
72 /// Constructs a new condvar initialiser.
73 pub fn new(name: &'static CStr, key: Pin<&'static LockClassKey>) -> impl PinInit<Self> {
74 pin_init!(Self {
75 inner <- CondVar::new(name, key),
76 })
77 }
78}
79
80// Make the `CondVar` methods callable on `PollCondVar`.
81impl Deref for PollCondVar {
82 type Target = CondVar;
83
84 fn deref(&self) -> &CondVar {
85 &self.inner
86 }
87}
88
89#[pinned_drop]
90impl PinnedDrop for PollCondVar {
91 fn drop(self: Pin<&mut Self>) {
92 // Clear anything registered using `register_wait`.
93 //
94 // SAFETY: The pointer points at a valid `wait_queue_head`.
95 unsafe { bindings::__wake_up_pollfree(self.inner.wait_queue_head.get()) };
96
97 // Wait for epoll items to be properly removed.
98 //
99 // SAFETY: Just an FFI call.
100 unsafe { bindings::synchronize_rcu() };
101 }
102}