1 // SPDX-License-Identifier: GPL-2.0 2 3 // Copyright (C) 2024 Google LLC. 4 5 //! Utilities for working with `struct poll_table`. 6 7 use crate::{ 8 bindings, 9 fs::File, 10 prelude::*, 11 sync::{CondVar, LockClassKey}, 12 types::Opaque, 13 }; 14 use core::ops::Deref; 15 16 /// Creates a [`PollCondVar`] initialiser with the given name and a newly-created lock class. 17 #[macro_export] 18 macro_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)] 39 pub struct PollTable(Opaque<bindings::poll_table>); 40 41 impl 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)] 85 pub struct PollCondVar { 86 #[pin] 87 inner: CondVar, 88 } 89 90 impl 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`. 100 impl Deref for PollCondVar { 101 type Target = CondVar; 102 103 fn deref(&self) -> &CondVar { 104 &self.inner 105 } 106 } 107 108 #[pinned_drop] 109 impl 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 } 122