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: &'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}