Something went wrong. Try again.
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238// SPDX-License-Identifier: GPL-2.0
//! Devres abstraction//!//! [`Devres`] represents an abstraction for the kernel devres (device resource management)//! implementation.
use crate::{ alloc::Flags, bindings, device::{Bound, Device}, error::{Error, Result}, ffi::c_void, prelude::*, revocable::Revocable, sync::Arc, types::ARef,};
use core::ops::Deref;
#[pin_data]struct DevresInner<T> { dev: ARef<Device>, callback: unsafe extern "C" fn(*mut c_void), #[pin] data: Revocable<T>,}
/// This abstraction is meant to be used by subsystems to containerize [`Device`] bound resources to/// manage their lifetime.////// [`Device`] bound resources should be freed when either the resource goes out of scope or the/// [`Device`] is unbound respectively, depending on what happens first.////// To achieve that [`Devres`] registers a devres callback on creation, which is called once the/// [`Device`] is unbound, revoking access to the encapsulated resource (see also [`Revocable`]).////// After the [`Devres`] has been unbound it is not possible to access the encapsulated resource/// anymore.////// [`Devres`] users should make sure to simply free the corresponding backing resource in `T`'s/// [`Drop`] implementation.////// # Example////// ```no_run/// # use kernel::{bindings, c_str, device::{Bound, Device}, devres::Devres, io::{Io, IoRaw}};/// # use core::ops::Deref;////// // See also [`pci::Bar`] for a real example./// struct IoMem<const SIZE: usize>(IoRaw<SIZE>);////// impl<const SIZE: usize> IoMem<SIZE> {/// /// # Safety/// ////// /// [`paddr`, `paddr` + `SIZE`) must be a valid MMIO region that is mappable into the CPUs/// /// virtual address space./// unsafe fn new(paddr: usize) -> Result<Self>{/// // SAFETY: By the safety requirements of this function [`paddr`, `paddr` + `SIZE`) is/// // valid for `ioremap`./// let addr = unsafe { bindings::ioremap(paddr as _, SIZE as _) };/// if addr.is_null() {/// return Err(ENOMEM);/// }////// Ok(IoMem(IoRaw::new(addr as _, SIZE)?))/// }/// }////// impl<const SIZE: usize> Drop for IoMem<SIZE> {/// fn drop(&mut self) {/// // SAFETY: `self.0.addr()` is guaranteed to be properly mapped by `Self::new`./// unsafe { bindings::iounmap(self.0.addr() as _); };/// }/// }////// impl<const SIZE: usize> Deref for IoMem<SIZE> {/// type Target = Io<SIZE>;////// fn deref(&self) -> &Self::Target {/// // SAFETY: The memory range stored in `self` has been properly mapped in `Self::new`./// unsafe { Io::from_raw(&self.0) }/// }/// }/// # fn no_run(dev: &Device<Bound>) -> Result<(), Error> {/// // SAFETY: Invalid usage for example purposes./// let iomem = unsafe { IoMem::<{ core::mem::size_of::<u32>() }>::new(0xBAAAAAAD)? };/// let devres = Devres::new(dev, iomem, GFP_KERNEL)?;////// let res = devres.try_access().ok_or(ENXIO)?;/// res.write8(0x42, 0x0);/// # Ok(())/// # }/// ```pub struct Devres<T>(Arc<DevresInner<T>>);
impl<T> DevresInner<T> { fn new(dev: &Device<Bound>, data: T, flags: Flags) -> Result<Arc<DevresInner<T>>> { let inner = Arc::pin_init( pin_init!( DevresInner { dev: dev.into(), callback: Self::devres_callback, data <- Revocable::new(data), }), flags, )?;
// Convert `Arc<DevresInner>` into a raw pointer and make devres own this reference until // `Self::devres_callback` is called. let data = inner.clone().into_raw();
// SAFETY: `devm_add_action` guarantees to call `Self::devres_callback` once `dev` is // detached. let ret = unsafe { bindings::devm_add_action(dev.as_raw(), Some(inner.callback), data as _) };
if ret != 0 { // SAFETY: We just created another reference to `inner` in order to pass it to // `bindings::devm_add_action`. If `bindings::devm_add_action` fails, we have to drop // this reference accordingly. let _ = unsafe { Arc::from_raw(data) }; return Err(Error::from_errno(ret)); }
Ok(inner) }
fn as_ptr(&self) -> *const Self { self as _ }
fn remove_action(this: &Arc<Self>) { // SAFETY: // - `self.inner.dev` is a valid `Device`, // - the `action` and `data` pointers are the exact same ones as given to devm_add_action() // previously, // - `self` is always valid, even if the action has been released already. let ret = unsafe { bindings::devm_remove_action_nowarn( this.dev.as_raw(), Some(this.callback), this.as_ptr() as _, ) };
if ret == 0 { // SAFETY: We leaked an `Arc` reference to devm_add_action() in `DevresInner::new`; if // devm_remove_action_nowarn() was successful we can (and have to) claim back ownership // of this reference. let _ = unsafe { Arc::from_raw(this.as_ptr()) }; } }
#[allow(clippy::missing_safety_doc)] unsafe extern "C" fn devres_callback(ptr: *mut kernel::ffi::c_void) { let ptr = ptr as *mut DevresInner<T>; // Devres owned this memory; now that we received the callback, drop the `Arc` and hence the // reference. // SAFETY: Safe, since we leaked an `Arc` reference to devm_add_action() in // `DevresInner::new`. let inner = unsafe { Arc::from_raw(ptr) };
inner.data.revoke(); }}
impl<T> Devres<T> { /// Creates a new [`Devres`] instance of the given `data`. The `data` encapsulated within the /// returned `Devres` instance' `data` will be revoked once the device is detached. pub fn new(dev: &Device<Bound>, data: T, flags: Flags) -> Result<Self> { let inner = DevresInner::new(dev, data, flags)?;
Ok(Devres(inner)) }
/// Same as [`Devres::new`], but does not return a `Devres` instance. Instead the given `data` /// is owned by devres and will be revoked / dropped, once the device is detached. pub fn new_foreign_owned(dev: &Device<Bound>, data: T, flags: Flags) -> Result { let _ = DevresInner::new(dev, data, flags)?;
Ok(()) }
/// Obtain `&'a T`, bypassing the [`Revocable`]. /// /// This method allows to directly obtain a `&'a T`, bypassing the [`Revocable`], by presenting /// a `&'a Device<Bound>` of the same [`Device`] this [`Devres`] instance has been created with. /// /// # Errors /// /// An error is returned if `dev` does not match the same [`Device`] this [`Devres`] instance /// has been created with. /// /// # Example /// /// ```no_run /// # #![cfg(CONFIG_PCI)] /// # use kernel::{device::Core, devres::Devres, pci}; /// /// fn from_core(dev: &pci::Device<Core>, devres: Devres<pci::Bar<0x4>>) -> Result { /// let bar = devres.access(dev.as_ref())?; /// /// let _ = bar.read32(0x0); /// /// // might_sleep() /// /// bar.write32(0x42, 0x0); /// /// Ok(()) /// } /// ``` pub fn access<'a>(&'a self, dev: &'a Device<Bound>) -> Result<&'a T> { if self.0.dev.as_raw() != dev.as_raw() { return Err(EINVAL); }
// SAFETY: `dev` being the same device as the device this `Devres` has been created for // proves that `self.0.data` hasn't been revoked and is guaranteed to not be revoked as // long as `dev` lives; `dev` lives at least as long as `self`. Ok(unsafe { self.deref().access() }) }}
impl<T> Deref for Devres<T> { type Target = Revocable<T>;
fn deref(&self) -> &Self::Target { &self.0.data }}
impl<T> Drop for Devres<T> { fn drop(&mut self) { DevresInner::remove_action(&self.0); }}