projects/linux·blob v6.16 · refs

263 lines · 9.4 KiB

1// SPDX-License-Identifier: GPL-2.0
2
3//! Devres abstraction
4//!
5//! [`Devres`] represents an abstraction for the kernel devres (device resource management)
6//! implementation.
7
8use crate::{
9 alloc::Flags,
10 bindings,
11 device::{Bound, Device},
12 error::{Error, Result},
13 ffi::c_void,
14 prelude::*,
15 revocable::{Revocable, RevocableGuard},
16 sync::{rcu, Arc, Completion},
17 types::ARef,
18};
19
20#[pin_data]
21struct DevresInner<T> {
22 dev: ARef<Device>,
23 callback: unsafe extern "C" fn(*mut c_void),
24 #[pin]
25 data: Revocable<T>,
26 #[pin]
27 revoke: Completion,
28}
29
30/// This abstraction is meant to be used by subsystems to containerize [`Device`] bound resources to
31/// manage their lifetime.
32///
33/// [`Device`] bound resources should be freed when either the resource goes out of scope or the
34/// [`Device`] is unbound respectively, depending on what happens first. In any case, it is always
35/// guaranteed that revoking the device resource is completed before the corresponding [`Device`]
36/// is unbound.
37///
38/// To achieve that [`Devres`] registers a devres callback on creation, which is called once the
39/// [`Device`] is unbound, revoking access to the encapsulated resource (see also [`Revocable`]).
40///
41/// After the [`Devres`] has been unbound it is not possible to access the encapsulated resource
42/// anymore.
43///
44/// [`Devres`] users should make sure to simply free the corresponding backing resource in `T`'s
45/// [`Drop`] implementation.
46///
47/// # Example
48///
49/// ```no_run
50/// # use kernel::{bindings, c_str, device::{Bound, Device}, devres::Devres, io::{Io, IoRaw}};
51/// # use core::ops::Deref;
52///
53/// // See also [`pci::Bar`] for a real example.
54/// struct IoMem<const SIZE: usize>(IoRaw<SIZE>);
55///
56/// impl<const SIZE: usize> IoMem<SIZE> {
57/// /// # Safety
58/// ///
59/// /// [`paddr`, `paddr` + `SIZE`) must be a valid MMIO region that is mappable into the CPUs
60/// /// virtual address space.
61/// unsafe fn new(paddr: usize) -> Result<Self>{
62/// // SAFETY: By the safety requirements of this function [`paddr`, `paddr` + `SIZE`) is
63/// // valid for `ioremap`.
64/// let addr = unsafe { bindings::ioremap(paddr as _, SIZE as _) };
65/// if addr.is_null() {
66/// return Err(ENOMEM);
67/// }
68///
69/// Ok(IoMem(IoRaw::new(addr as _, SIZE)?))
70/// }
71/// }
72///
73/// impl<const SIZE: usize> Drop for IoMem<SIZE> {
74/// fn drop(&mut self) {
75/// // SAFETY: `self.0.addr()` is guaranteed to be properly mapped by `Self::new`.
76/// unsafe { bindings::iounmap(self.0.addr() as _); };
77/// }
78/// }
79///
80/// impl<const SIZE: usize> Deref for IoMem<SIZE> {
81/// type Target = Io<SIZE>;
82///
83/// fn deref(&self) -> &Self::Target {
84/// // SAFETY: The memory range stored in `self` has been properly mapped in `Self::new`.
85/// unsafe { Io::from_raw(&self.0) }
86/// }
87/// }
88/// # fn no_run(dev: &Device<Bound>) -> Result<(), Error> {
89/// // SAFETY: Invalid usage for example purposes.
90/// let iomem = unsafe { IoMem::<{ core::mem::size_of::<u32>() }>::new(0xBAAAAAAD)? };
91/// let devres = Devres::new(dev, iomem, GFP_KERNEL)?;
92///
93/// let res = devres.try_access().ok_or(ENXIO)?;
94/// res.write8(0x42, 0x0);
95/// # Ok(())
96/// # }
97/// ```
98pub struct Devres<T>(Arc<DevresInner<T>>);
99
100impl<T> DevresInner<T> {
101 fn new(dev: &Device<Bound>, data: T, flags: Flags) -> Result<Arc<DevresInner<T>>> {
102 let inner = Arc::pin_init(
103 pin_init!( DevresInner {
104 dev: dev.into(),
105 callback: Self::devres_callback,
106 data <- Revocable::new(data),
107 revoke <- Completion::new(),
108 }),
109 flags,
110 )?;
111
112 // Convert `Arc<DevresInner>` into a raw pointer and make devres own this reference until
113 // `Self::devres_callback` is called.
114 let data = inner.clone().into_raw();
115
116 // SAFETY: `devm_add_action` guarantees to call `Self::devres_callback` once `dev` is
117 // detached.
118 let ret =
119 unsafe { bindings::devm_add_action(dev.as_raw(), Some(inner.callback), data as _) };
120
121 if ret != 0 {
122 // SAFETY: We just created another reference to `inner` in order to pass it to
123 // `bindings::devm_add_action`. If `bindings::devm_add_action` fails, we have to drop
124 // this reference accordingly.
125 let _ = unsafe { Arc::from_raw(data) };
126 return Err(Error::from_errno(ret));
127 }
128
129 Ok(inner)
130 }
131
132 fn as_ptr(&self) -> *const Self {
133 self as _
134 }
135
136 fn remove_action(this: &Arc<Self>) -> bool {
137 // SAFETY:
138 // - `self.inner.dev` is a valid `Device`,
139 // - the `action` and `data` pointers are the exact same ones as given to devm_add_action()
140 // previously,
141 // - `self` is always valid, even if the action has been released already.
142 let success = unsafe {
143 bindings::devm_remove_action_nowarn(
144 this.dev.as_raw(),
145 Some(this.callback),
146 this.as_ptr() as _,
147 )
148 } == 0;
149
150 if success {
151 // SAFETY: We leaked an `Arc` reference to devm_add_action() in `DevresInner::new`; if
152 // devm_remove_action_nowarn() was successful we can (and have to) claim back ownership
153 // of this reference.
154 let _ = unsafe { Arc::from_raw(this.as_ptr()) };
155 }
156
157 success
158 }
159
160 #[allow(clippy::missing_safety_doc)]
161 unsafe extern "C" fn devres_callback(ptr: *mut kernel::ffi::c_void) {
162 let ptr = ptr as *mut DevresInner<T>;
163 // Devres owned this memory; now that we received the callback, drop the `Arc` and hence the
164 // reference.
165 // SAFETY: Safe, since we leaked an `Arc` reference to devm_add_action() in
166 // `DevresInner::new`.
167 let inner = unsafe { Arc::from_raw(ptr) };
168
169 if !inner.data.revoke() {
170 // If `revoke()` returns false, it means that `Devres::drop` already started revoking
171 // `inner.data` for us. Hence we have to wait until `Devres::drop()` signals that it
172 // completed revoking `inner.data`.
173 inner.revoke.wait_for_completion();
174 }
175 }
176}
177
178impl<T> Devres<T> {
179 /// Creates a new [`Devres`] instance of the given `data`. The `data` encapsulated within the
180 /// returned `Devres` instance' `data` will be revoked once the device is detached.
181 pub fn new(dev: &Device<Bound>, data: T, flags: Flags) -> Result<Self> {
182 let inner = DevresInner::new(dev, data, flags)?;
183
184 Ok(Devres(inner))
185 }
186
187 /// Same as [`Devres::new`], but does not return a `Devres` instance. Instead the given `data`
188 /// is owned by devres and will be revoked / dropped, once the device is detached.
189 pub fn new_foreign_owned(dev: &Device<Bound>, data: T, flags: Flags) -> Result {
190 let _ = DevresInner::new(dev, data, flags)?;
191
192 Ok(())
193 }
194
195 /// Obtain `&'a T`, bypassing the [`Revocable`].
196 ///
197 /// This method allows to directly obtain a `&'a T`, bypassing the [`Revocable`], by presenting
198 /// a `&'a Device<Bound>` of the same [`Device`] this [`Devres`] instance has been created with.
199 ///
200 /// # Errors
201 ///
202 /// An error is returned if `dev` does not match the same [`Device`] this [`Devres`] instance
203 /// has been created with.
204 ///
205 /// # Example
206 ///
207 /// ```no_run
208 /// # #![cfg(CONFIG_PCI)]
209 /// # use kernel::{device::Core, devres::Devres, pci};
210 ///
211 /// fn from_core(dev: &pci::Device<Core>, devres: Devres<pci::Bar<0x4>>) -> Result {
212 /// let bar = devres.access(dev.as_ref())?;
213 ///
214 /// let _ = bar.read32(0x0);
215 ///
216 /// // might_sleep()
217 ///
218 /// bar.write32(0x42, 0x0);
219 ///
220 /// Ok(())
221 /// }
222 /// ```
223 pub fn access<'a>(&'a self, dev: &'a Device<Bound>) -> Result<&'a T> {
224 if self.0.dev.as_raw() != dev.as_raw() {
225 return Err(EINVAL);
226 }
227
228 // SAFETY: `dev` being the same device as the device this `Devres` has been created for
229 // proves that `self.0.data` hasn't been revoked and is guaranteed to not be revoked as
230 // long as `dev` lives; `dev` lives at least as long as `self`.
231 Ok(unsafe { self.0.data.access() })
232 }
233
234 /// [`Devres`] accessor for [`Revocable::try_access`].
235 pub fn try_access(&self) -> Option<RevocableGuard<'_, T>> {
236 self.0.data.try_access()
237 }
238
239 /// [`Devres`] accessor for [`Revocable::try_access_with`].
240 pub fn try_access_with<R, F: FnOnce(&T) -> R>(&self, f: F) -> Option<R> {
241 self.0.data.try_access_with(f)
242 }
243
244 /// [`Devres`] accessor for [`Revocable::try_access_with_guard`].
245 pub fn try_access_with_guard<'a>(&'a self, guard: &'a rcu::Guard) -> Option<&'a T> {
246 self.0.data.try_access_with_guard(guard)
247 }
248}
249
250impl<T> Drop for Devres<T> {
251 fn drop(&mut self) {
252 // SAFETY: When `drop` runs, it is guaranteed that nobody is accessing the revocable data
253 // anymore, hence it is safe not to wait for the grace period to finish.
254 if unsafe { self.0.data.revoke_nosync() } {
255 // We revoked `self.0.data` before the devres action did, hence try to remove it.
256 if !DevresInner::remove_action(&self.0) {
257 // We could not remove the devres action, which means that it now runs concurrently,
258 // hence signal that `self.0.data` has been revoked successfully.
259 self.0.revoke.complete_all();
260 }
261 }
262 }
263}