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};
14use safety_macro::safety;
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    #[safety{ValidPtr, Owning}]
43    pub unsafe fn from_raw(table: *mut bindings::poll_table) -> Self {
44        // INVARIANTS: The safety requirements are the same as the struct invariants.
45        PollTable {
46            table,
47            _lifetime: PhantomData,
48        }
49    }
50
51    /// Register this [`PollTable`] with the provided [`PollCondVar`], so that it can be notified
52    /// using the condition variable.
53    pub fn register_wait(&self, file: &File, cv: &PollCondVar) {
54        // SAFETY:
55        // * `file.as_ptr()` references a valid file for the duration of this call.
56        // * `self.table` is null or references a valid poll_table for the duration of this call.
57        // * Since `PollCondVar` is pinned, its destructor is guaranteed to run before the memory
58        //   containing `cv.wait_queue_head` is invalidated. Since the destructor clears all
59        //   waiters and then waits for an rcu grace period, it's guaranteed that
60        //   `cv.wait_queue_head` remains valid for at least an rcu grace period after the removal
61        //   of the last waiter.
62        unsafe { bindings::poll_wait(file.as_ptr(), cv.wait_queue_head.get(), self.table) }
63    }
64}
65
66/// A wrapper around [`CondVar`] that makes it usable with [`PollTable`].
67///
68/// [`CondVar`]: crate::sync::CondVar
69#[pin_data(PinnedDrop)]
70pub struct PollCondVar {
71    #[pin]
72    inner: CondVar,
73}
74
75impl PollCondVar {
76    /// Constructs a new condvar initialiser.
77    pub fn new(name: &'static CStr, key: Pin<&'static LockClassKey>) -> impl PinInit<Self> {
78        pin_init!(Self {
79            inner <- CondVar::new(name, key),
80        })
81    }
82}
83
84// Make the `CondVar` methods callable on `PollCondVar`.
85impl Deref for PollCondVar {
86    type Target = CondVar;
87
88    fn deref(&self) -> &CondVar {
89        &self.inner
90    }
91}
92
93#[pinned_drop]
94impl PinnedDrop for PollCondVar {
95    #[inline]
96    fn drop(self: Pin<&mut Self>) {
97        // Clear anything registered using `register_wait`.
98        //
99        // SAFETY: The pointer points at a valid `wait_queue_head`.
100        unsafe { bindings::__wake_up_pollfree(self.inner.wait_queue_head.get()) };
101
102        // Wait for epoll items to be properly removed.
103        //
104        // SAFETY: Just an FFI call.
105        unsafe { bindings::synchronize_rcu() };
106    }
107}
kernel/sync/poll.rs

kernel/sync/
poll.rs
