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    types::Opaque,
13};
14use core::ops::Deref;
15
16/// Creates a [`PollCondVar`] initialiser with the given name and a newly-created lock class.
17#[macro_export]
18macro_rules! new_poll_condvar {
19    ($($name:literal)?) => {
20        $crate::sync::poll::PollCondVar::new(
21            $crate::optional_name!($($name)?), $crate::static_lock_class!()
22        )
23    };
24}
25
26/// Wraps the kernel's `struct poll_table`.
27///
28/// # Invariants
29///
30/// This struct contains a valid `struct poll_table`.
31///
32/// For a `struct poll_table` to be valid, its `_qproc` function must follow the safety
33/// requirements of `_qproc` functions:
34///
35/// * The `_qproc` function is given permission to enqueue a waiter to the provided `poll_table`
36///   during the call. Once the waiter is removed and an rcu grace period has passed, it must no
37///   longer access the `wait_queue_head`.
38#[repr(transparent)]
39pub struct PollTable(Opaque<bindings::poll_table>);
40
41impl PollTable {
42    /// Creates a reference to a [`PollTable`] from a valid pointer.
43    ///
44    /// # Safety
45    ///
46    /// The caller must ensure that for the duration of `'a`, the pointer will point at a valid poll
47    /// table (as defined in the type invariants).
48    ///
49    /// The caller must also ensure that the `poll_table` is only accessed via the returned
50    /// reference for the duration of `'a`.
51    pub unsafe fn from_ptr<'a>(ptr: *mut bindings::poll_table) -> &'a mut PollTable {
52        // SAFETY: The safety requirements guarantee the validity of the dereference, while the
53        // `PollTable` type being transparent makes the cast ok.
54        unsafe { &mut *ptr.cast() }
55    }
56
57    fn get_qproc(&self) -> bindings::poll_queue_proc {
58        let ptr = self.0.get();
59        // SAFETY: The `ptr` is valid because it originates from a reference, and the `_qproc`
60        // field is not modified concurrently with this call since we have an immutable reference.
61        unsafe { (*ptr)._qproc }
62    }
63
64    /// Register this [`PollTable`] with the provided [`PollCondVar`], so that it can be notified
65    /// using the condition variable.
66    pub fn register_wait(&mut self, file: &File, cv: &PollCondVar) {
67        if let Some(qproc) = self.get_qproc() {
68            // SAFETY: The pointers to `file` and `self` need to be valid for the duration of this
69            // call to `qproc`, which they are because they are references.
70            //
71            // The `cv.wait_queue_head` pointer must be valid until an rcu grace period after the
72            // waiter is removed. The `PollCondVar` is pinned, so before `cv.wait_queue_head` can
73            // be destroyed, the destructor must run. That destructor first removes all waiters,
74            // and then waits for an rcu grace period. Therefore, `cv.wait_queue_head` is valid for
75            // long enough.
76            unsafe { qproc(file.as_ptr() as _, cv.wait_queue_head.get(), self.0.get()) };
77        }
78    }
79}
80
81/// A wrapper around [`CondVar`] that makes it usable with [`PollTable`].
82///
83/// [`CondVar`]: crate::sync::CondVar
84#[pin_data(PinnedDrop)]
85pub struct PollCondVar {
86    #[pin]
87    inner: CondVar,
88}
89
90impl PollCondVar {
91    /// Constructs a new condvar initialiser.
92    pub fn new(name: &'static CStr, key: Pin<&'static LockClassKey>) -> impl PinInit<Self> {
93        pin_init!(Self {
94            inner <- CondVar::new(name, key),
95        })
96    }
97}
98
99// Make the `CondVar` methods callable on `PollCondVar`.
100impl Deref for PollCondVar {
101    type Target = CondVar;
102
103    fn deref(&self) -> &CondVar {
104        &self.inner
105    }
106}
107
108#[pinned_drop]
109impl PinnedDrop for PollCondVar {
110    fn drop(self: Pin<&mut Self>) {
111        // Clear anything registered using `register_wait`.
112        //
113        // SAFETY: The pointer points at a valid `wait_queue_head`.
114        unsafe { bindings::__wake_up_pollfree(self.inner.wait_queue_head.get()) };
115
116        // Wait for epoll items to be properly removed.
117        //
118        // SAFETY: Just an FFI call.
119        unsafe { bindings::synchronize_rcu() };
120    }
121}
kernel/sync/poll.rs

kernel/sync/
poll.rs
