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

kernel/
devres.rs
