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 }; 13 use core::{marker::PhantomData, ops::Deref}; 14 15 /// Creates a [`PollCondVar`] initialiser with the given name and a newly-created lock class. 16 #[macro_export] 17 macro_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)] 31 pub struct PollTable<'a> { 32 table: *mut bindings::poll_table, 33 _lifetime: PhantomData<&'a bindings::poll_table>, 34 } 35 36 impl<'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`. from_raw(table: *mut bindings::poll_table) -> Self42 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. register_wait(&self, file: &File, cv: &PollCondVar)52 pub fn register_wait(&self, file: &File, cv: &PollCondVar) { 53 // SAFETY: 54 // * `file.as_ptr()` references a valid file for the duration of this call. 55 // * `self.table` is null or references a valid poll_table for the duration of this call. 56 // * Since `PollCondVar` is pinned, its destructor is guaranteed to run before the memory 57 // containing `cv.wait_queue_head` is invalidated. Since the destructor clears all 58 // waiters and then waits for an rcu grace period, it's guaranteed that 59 // `cv.wait_queue_head` remains valid for at least an rcu grace period after the removal 60 // of the last waiter. 61 unsafe { bindings::poll_wait(file.as_ptr(), cv.wait_queue_head.get(), self.table) } 62 } 63 } 64 65 /// A wrapper around [`CondVar`] that makes it usable with [`PollTable`]. 66 /// 67 /// [`CondVar`]: crate::sync::CondVar 68 #[pin_data(PinnedDrop)] 69 pub struct PollCondVar { 70 #[pin] 71 inner: CondVar, 72 } 73 74 impl PollCondVar { 75 /// Constructs a new condvar initialiser. new(name: &'static CStr, key: Pin<&'static LockClassKey>) -> impl PinInit<Self>76 pub fn new(name: &'static CStr, key: Pin<&'static LockClassKey>) -> impl PinInit<Self> { 77 pin_init!(Self { 78 inner <- CondVar::new(name, key), 79 }) 80 } 81 } 82 83 // Make the `CondVar` methods callable on `PollCondVar`. 84 impl Deref for PollCondVar { 85 type Target = CondVar; 86 deref(&self) -> &CondVar87 fn deref(&self) -> &CondVar { 88 &self.inner 89 } 90 } 91 92 #[pinned_drop] 93 impl PinnedDrop for PollCondVar { 94 #[inline] drop(self: Pin<&mut Self>)95 fn drop(self: Pin<&mut Self>) { 96 // Clear anything registered using `register_wait`. 97 // 98 // SAFETY: The pointer points at a valid `wait_queue_head`. 99 unsafe { bindings::__wake_up_pollfree(self.inner.wait_queue_head.get()) }; 100 101 // Wait for epoll items to be properly removed. 102 // 103 // SAFETY: Just an FFI call. 104 unsafe { bindings::synchronize_rcu() }; 105 } 106 } 107