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