| 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: 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`. |
|---|
| 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 | |
|---|
