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

kernel/
devres.rs
