kernel/devres.rs
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::{to_result, Error, Result},
13 ffi::c_void,
14 prelude::*,
15 revocable::{Revocable, RevocableGuard},
16 sync::{aref::ARef, rcu, Completion},
17 types::{ForeignOwnable, Opaque, ScopeGuard},
18};
19
20use pin_init::Wrapper;
21
22/// [`Devres`] inner data accessed from [`Devres::callback`].
23#[pin_data]
24struct Inner<T: Send> {
25 #[pin]
26 data: Revocable<T>,
27 /// Tracks whether [`Devres::callback`] has been completed.
28 #[pin]
29 devm: Completion,
30 /// Tracks whether revoking [`Self::data`] has been completed.
31 #[pin]
32 revoke: Completion,
33}
34
35/// This abstraction is meant to be used by subsystems to containerize [`Device`] bound resources to
36/// manage their lifetime.
37///
38/// [`Device`] bound resources should be freed when either the resource goes out of scope or the
39/// [`Device`] is unbound respectively, depending on what happens first. In any case, it is always
40/// guaranteed that revoking the device resource is completed before the corresponding [`Device`]
41/// is unbound.
42///
43/// To achieve that [`Devres`] registers a devres callback on creation, which is called once the
44/// [`Device`] is unbound, revoking access to the encapsulated resource (see also [`Revocable`]).
45///
46/// After the [`Devres`] has been unbound it is not possible to access the encapsulated resource
47/// anymore.
48///
49/// [`Devres`] users should make sure to simply free the corresponding backing resource in `T`'s
50/// [`Drop`] implementation.
51///
52/// # Examples
53///
54/// ```no_run
55/// # use kernel::{bindings, device::{Bound, Device}, devres::Devres, io::{Io, IoRaw}};
56/// # use core::ops::Deref;
57///
58/// // See also [`pci::Bar`] for a real example.
59/// struct IoMem<const SIZE: usize>(IoRaw<SIZE>);
60///
61/// impl<const SIZE: usize> IoMem<SIZE> {
62/// /// # Safety
63/// ///
64/// /// [`paddr`, `paddr` + `SIZE`) must be a valid MMIO region that is mappable into the CPUs
65/// /// virtual address space.
66/// unsafe fn new(paddr: usize) -> Result<Self>{
67/// // SAFETY: By the safety requirements of this function [`paddr`, `paddr` + `SIZE`) is
68/// // valid for `ioremap`.
69/// let addr = unsafe { bindings::ioremap(paddr as bindings::phys_addr_t, SIZE) };
70/// if addr.is_null() {
71/// return Err(ENOMEM);
72/// }
73///
74/// Ok(IoMem(IoRaw::new(addr as usize, SIZE)?))
75/// }
76/// }
77///
78/// impl<const SIZE: usize> Drop for IoMem<SIZE> {
79/// fn drop(&mut self) {
80/// // SAFETY: `self.0.addr()` is guaranteed to be properly mapped by `Self::new`.
81/// unsafe { bindings::iounmap(self.0.addr() as *mut c_void); };
82/// }
83/// }
84///
85/// impl<const SIZE: usize> Deref for IoMem<SIZE> {
86/// type Target = Io<SIZE>;
87///
88/// fn deref(&self) -> &Self::Target {
89/// // SAFETY: The memory range stored in `self` has been properly mapped in `Self::new`.
90/// unsafe { Io::from_raw(&self.0) }
91/// }
92/// }
93/// # fn no_run(dev: &Device<Bound>) -> Result<(), Error> {
94/// // SAFETY: Invalid usage for example purposes.
95/// let iomem = unsafe { IoMem::<{ core::mem::size_of::<u32>() }>::new(0xBAAAAAAD)? };
96/// let devres = KBox::pin_init(Devres::new(dev, iomem), GFP_KERNEL)?;
97///
98/// let res = devres.try_access().ok_or(ENXIO)?;
99/// res.write8(0x42, 0x0);
100/// # Ok(())
101/// # }
102/// ```
103///
104/// # Invariants
105///
106/// [`Self::inner`] is guaranteed to be initialized and is always accessed read-only.
107#[pin_data(PinnedDrop)]
108pub struct Devres<T: Send> {
109 dev: ARef<Device>,
110 /// Pointer to [`Self::devres_callback`].
111 ///
112 /// Has to be stored, since Rust does not guarantee to always return the same address for a
113 /// function. However, the C API uses the address as a key.
114 callback: unsafe extern "C" fn(*mut c_void),
115 /// Contains all the fields shared with [`Self::callback`].
116 // TODO: Replace with `UnsafePinned`, once available.
117 //
118 // Subsequently, the `drop_in_place()` in `Devres::drop` and `Devres::new` as well as the
119 // explicit `Send` and `Sync' impls can be removed.
120 #[pin]
121 inner: Opaque<Inner<T>>,
122 _add_action: (),
123}
124
125impl<T: Send> Devres<T> {
126 /// Creates a new [`Devres`] instance of the given `data`.
127 ///
128 /// The `data` encapsulated within the returned `Devres` instance' `data` will be
129 /// (revoked)[`Revocable`] once the device is detached.
130 pub fn new<'a, E>(
131 dev: &'a Device<Bound>,
132 data: impl PinInit<T, E> + 'a,
133 ) -> impl PinInit<Self, Error> + 'a
134 where
135 T: 'a,
136 Error: From<E>,
137 {
138 try_pin_init!(&this in Self {
139 dev: dev.into(),
140 callback: Self::devres_callback,
141 // INVARIANT: `inner` is properly initialized.
142 inner <- Opaque::pin_init(try_pin_init!(Inner {
143 devm <- Completion::new(),
144 revoke <- Completion::new(),
145 data <- Revocable::new(data),
146 })),
147 // TODO: Replace with "initializer code blocks" [1] once available.
148 //
149 // [1] https://github.com/Rust-for-Linux/pin-init/pull/69
150 _add_action: {
151 // SAFETY: `this` is a valid pointer to uninitialized memory.
152 let inner = unsafe { &raw mut (*this.as_ptr()).inner };
153
154 // SAFETY:
155 // - `dev.as_raw()` is a pointer to a valid bound device.
156 // - `inner` is guaranteed to be a valid for the duration of the lifetime of `Self`.
157 // - `devm_add_action()` is guaranteed not to call `callback` until `this` has been
158 // properly initialized, because we require `dev` (i.e. the *bound* device) to
159 // live at least as long as the returned `impl PinInit<Self, Error>`.
160 to_result(unsafe {
161 bindings::devm_add_action(dev.as_raw(), Some(*callback), inner.cast())
162 }).inspect_err(|_| {
163 let inner = Opaque::cast_into(inner);
164
165 // SAFETY: `inner` is a valid pointer to an `Inner<T>` and valid for both reads
166 // and writes.
167 unsafe { core::ptr::drop_in_place(inner) };
168 })?;
169 },
170 })
171 }
172
173 fn inner(&self) -> &Inner<T> {
174 // SAFETY: By the type invairants of `Self`, `inner` is properly initialized and always
175 // accessed read-only.
176 unsafe { &*self.inner.get() }
177 }
178
179 fn data(&self) -> &Revocable<T> {
180 &self.inner().data
181 }
182
183 #[allow(clippy::missing_safety_doc)]
184 unsafe extern "C" fn devres_callback(ptr: *mut kernel::ffi::c_void) {
185 // SAFETY: In `Self::new` we've passed a valid pointer to `Inner` to `devm_add_action()`,
186 // hence `ptr` must be a valid pointer to `Inner`.
187 let inner = unsafe { &*ptr.cast::<Inner<T>>() };
188
189 // Ensure that `inner` can't be used anymore after we signal completion of this callback.
190 let inner = ScopeGuard::new_with_data(inner, |inner| inner.devm.complete_all());
191
192 if !inner.data.revoke() {
193 // If `revoke()` returns false, it means that `Devres::drop` already started revoking
194 // `data` for us. Hence we have to wait until `Devres::drop` signals that it
195 // completed revoking `data`.
196 inner.revoke.wait_for_completion();
197 }
198 }
199
200 fn remove_action(&self) -> bool {
201 // SAFETY:
202 // - `self.dev` is a valid `Device`,
203 // - the `action` and `data` pointers are the exact same ones as given to
204 // `devm_add_action()` previously,
205 (unsafe {
206 bindings::devm_remove_action_nowarn(
207 self.dev.as_raw(),
208 Some(self.callback),
209 core::ptr::from_ref(self.inner()).cast_mut().cast(),
210 )
211 } == 0)
212 }
213
214 /// Return a reference of the [`Device`] this [`Devres`] instance has been created with.
215 pub fn device(&self) -> &Device {
216 &self.dev
217 }
218
219 /// Obtain `&'a T`, bypassing the [`Revocable`].
220 ///
221 /// This method allows to directly obtain a `&'a T`, bypassing the [`Revocable`], by presenting
222 /// a `&'a Device<Bound>` of the same [`Device`] this [`Devres`] instance has been created with.
223 ///
224 /// # Errors
225 ///
226 /// An error is returned if `dev` does not match the same [`Device`] this [`Devres`] instance
227 /// has been created with.
228 ///
229 /// # Examples
230 ///
231 /// ```no_run
232 /// # #![cfg(CONFIG_PCI)]
233 /// # use kernel::{device::Core, devres::Devres, pci};
234 ///
235 /// fn from_core(dev: &pci::Device<Core>, devres: Devres<pci::Bar<0x4>>) -> Result {
236 /// let bar = devres.access(dev.as_ref())?;
237 ///
238 /// let _ = bar.read32(0x0);
239 ///
240 /// // might_sleep()
241 ///
242 /// bar.write32(0x42, 0x0);
243 ///
244 /// Ok(())
245 /// }
246 /// ```
247 pub fn access<'a>(&'a self, dev: &'a Device<Bound>) -> Result<&'a T> {
248 if self.dev.as_raw() != dev.as_raw() {
249 return Err(EINVAL);
250 }
251
252 // SAFETY: `dev` being the same device as the device this `Devres` has been created for
253 // proves that `self.data` hasn't been revoked and is guaranteed to not be revoked as long
254 // as `dev` lives; `dev` lives at least as long as `self`.
255 Ok(unsafe { self.data().access() })
256 }
257
258 /// [`Devres`] accessor for [`Revocable::try_access`].
259 pub fn try_access(&self) -> Option<RevocableGuard<'_, T>> {
260 self.data().try_access()
261 }
262
263 /// [`Devres`] accessor for [`Revocable::try_access_with`].
264 pub fn try_access_with<R, F: FnOnce(&T) -> R>(&self, f: F) -> Option<R> {
265 self.data().try_access_with(f)
266 }
267
268 /// [`Devres`] accessor for [`Revocable::try_access_with_guard`].
269 pub fn try_access_with_guard<'a>(&'a self, guard: &'a rcu::Guard) -> Option<&'a T> {
270 self.data().try_access_with_guard(guard)
271 }
272}
273
274// SAFETY: `Devres` can be send to any task, if `T: Send`.
275unsafe impl<T: Send> Send for Devres<T> {}
276
277// SAFETY: `Devres` can be shared with any task, if `T: Sync`.
278unsafe impl<T: Send + Sync> Sync for Devres<T> {}
279
280#[pinned_drop]
281impl<T: Send> PinnedDrop for Devres<T> {
282 fn drop(self: Pin<&mut Self>) {
283 // SAFETY: When `drop` runs, it is guaranteed that nobody is accessing the revocable data
284 // anymore, hence it is safe not to wait for the grace period to finish.
285 if unsafe { self.data().revoke_nosync() } {
286 // We revoked `self.data` before the devres action did, hence try to remove it.
287 if !self.remove_action() {
288 // We could not remove the devres action, which means that it now runs concurrently,
289 // hence signal that `self.data` has been revoked by us successfully.
290 self.inner().revoke.complete_all();
291
292 // Wait for `Self::devres_callback` to be done using this object.
293 self.inner().devm.wait_for_completion();
294 }
295 } else {
296 // `Self::devres_callback` revokes `self.data` for us, hence wait for it to be done
297 // using this object.
298 self.inner().devm.wait_for_completion();
299 }
300
301 // INVARIANT: At this point it is guaranteed that `inner` can't be accessed any more.
302 //
303 // SAFETY: `inner` is valid for dropping.
304 unsafe { core::ptr::drop_in_place(self.inner.get()) };
305 }
306}
307
308/// Consume `data` and [`Drop::drop`] `data` once `dev` is unbound.
309fn register_foreign<P>(dev: &Device<Bound>, data: P) -> Result
310where
311 P: ForeignOwnable + Send + 'static,
312{
313 let ptr = data.into_foreign();
314
315 #[allow(clippy::missing_safety_doc)]
316 unsafe extern "C" fn callback<P: ForeignOwnable>(ptr: *mut kernel::ffi::c_void) {
317 // SAFETY: `ptr` is the pointer to the `ForeignOwnable` leaked above and hence valid.
318 drop(unsafe { P::from_foreign(ptr.cast()) });
319 }
320
321 // SAFETY:
322 // - `dev.as_raw()` is a pointer to a valid and bound device.
323 // - `ptr` is a valid pointer the `ForeignOwnable` devres takes ownership of.
324 to_result(unsafe {
325 // `devm_add_action_or_reset()` also calls `callback` on failure, such that the
326 // `ForeignOwnable` is released eventually.
327 bindings::devm_add_action_or_reset(dev.as_raw(), Some(callback::<P>), ptr.cast())
328 })
329}
330
331/// Encapsulate `data` in a [`KBox`] and [`Drop::drop`] `data` once `dev` is unbound.
332///
333/// # Examples
334///
335/// ```no_run
336/// use kernel::{device::{Bound, Device}, devres};
337///
338/// /// Registration of e.g. a class device, IRQ, etc.
339/// struct Registration;
340///
341/// impl Registration {
342/// fn new() -> Self {
343/// // register
344///
345/// Self
346/// }
347/// }
348///
349/// impl Drop for Registration {
350/// fn drop(&mut self) {
351/// // unregister
352/// }
353/// }
354///
355/// fn from_bound_context(dev: &Device<Bound>) -> Result {
356/// devres::register(dev, Registration::new(), GFP_KERNEL)
357/// }
358/// ```
359pub fn register<T, E>(dev: &Device<Bound>, data: impl PinInit<T, E>, flags: Flags) -> Result
360where
361 T: Send + 'static,
362 Error: From<E>,
363{
364 let data = KBox::pin_init(data, flags)?;
365
366 register_foreign(dev, data)
367}