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

kernel/
devres.rs
