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 8 use crate::{ 9 alloc::Flags, 10 bindings, 11 device::{Bound, Device}, 12 error::{Error, Result}, 13 ffi::c_void, 14 prelude::*, 15 revocable::{Revocable, RevocableGuard}, 16 sync::{rcu, Arc, Completion}, 17 types::ARef, 18 }; 19 20 #[pin_data] 21 struct DevresInner<T> { 22 dev: ARef<Device>, 23 callback: unsafe extern "C" fn(*mut c_void), 24 #[pin] 25 data: Revocable<T>, 26 #[pin] 27 revoke: Completion, 28 } 29 30 /// This abstraction is meant to be used by subsystems to containerize [`Device`] bound resources to 31 /// manage their lifetime. 32 /// 33 /// [`Device`] bound resources should be freed when either the resource goes out of scope or the 34 /// [`Device`] is unbound respectively, depending on what happens first. In any case, it is always 35 /// guaranteed that revoking the device resource is completed before the corresponding [`Device`] 36 /// is unbound. 37 /// 38 /// To achieve that [`Devres`] registers a devres callback on creation, which is called once the 39 /// [`Device`] is unbound, revoking access to the encapsulated resource (see also [`Revocable`]). 40 /// 41 /// After the [`Devres`] has been unbound it is not possible to access the encapsulated resource 42 /// anymore. 43 /// 44 /// [`Devres`] users should make sure to simply free the corresponding backing resource in `T`'s 45 /// [`Drop`] implementation. 46 /// 47 /// # Example 48 /// 49 /// ```no_run 50 /// # use kernel::{bindings, c_str, device::{Bound, Device}, devres::Devres, io::{Io, IoRaw}}; 51 /// # use core::ops::Deref; 52 /// 53 /// // See also [`pci::Bar`] for a real example. 54 /// struct IoMem<const SIZE: usize>(IoRaw<SIZE>); 55 /// 56 /// impl<const SIZE: usize> IoMem<SIZE> { 57 /// /// # Safety 58 /// /// 59 /// /// [`paddr`, `paddr` + `SIZE`) must be a valid MMIO region that is mappable into the CPUs 60 /// /// virtual address space. 61 /// unsafe fn new(paddr: usize) -> Result<Self>{ 62 /// // SAFETY: By the safety requirements of this function [`paddr`, `paddr` + `SIZE`) is 63 /// // valid for `ioremap`. 64 /// let addr = unsafe { bindings::ioremap(paddr as _, SIZE as _) }; 65 /// if addr.is_null() { 66 /// return Err(ENOMEM); 67 /// } 68 /// 69 /// Ok(IoMem(IoRaw::new(addr as _, SIZE)?)) 70 /// } 71 /// } 72 /// 73 /// impl<const SIZE: usize> Drop for IoMem<SIZE> { 74 /// fn drop(&mut self) { 75 /// // SAFETY: `self.0.addr()` is guaranteed to be properly mapped by `Self::new`. 76 /// unsafe { bindings::iounmap(self.0.addr() as _); }; 77 /// } 78 /// } 79 /// 80 /// impl<const SIZE: usize> Deref for IoMem<SIZE> { 81 /// type Target = Io<SIZE>; 82 /// 83 /// fn deref(&self) -> &Self::Target { 84 /// // SAFETY: The memory range stored in `self` has been properly mapped in `Self::new`. 85 /// unsafe { Io::from_raw(&self.0) } 86 /// } 87 /// } 88 /// # fn no_run(dev: &Device<Bound>) -> Result<(), Error> { 89 /// // SAFETY: Invalid usage for example purposes. 90 /// let iomem = unsafe { IoMem::<{ core::mem::size_of::<u32>() }>::new(0xBAAAAAAD)? }; 91 /// let devres = Devres::new(dev, iomem, GFP_KERNEL)?; 92 /// 93 /// let res = devres.try_access().ok_or(ENXIO)?; 94 /// res.write8(0x42, 0x0); 95 /// # Ok(()) 96 /// # } 97 /// ``` 98 pub struct Devres<T>(Arc<DevresInner<T>>); 99 100 impl<T> DevresInner<T> { new(dev: &Device<Bound>, data: T, flags: Flags) -> Result<Arc<DevresInner<T>>>101 fn new(dev: &Device<Bound>, data: T, flags: Flags) -> Result<Arc<DevresInner<T>>> { 102 let inner = Arc::pin_init( 103 pin_init!( DevresInner { 104 dev: dev.into(), 105 callback: Self::devres_callback, 106 data <- Revocable::new(data), 107 revoke <- Completion::new(), 108 }), 109 flags, 110 )?; 111 112 // Convert `Arc<DevresInner>` into a raw pointer and make devres own this reference until 113 // `Self::devres_callback` is called. 114 let data = inner.clone().into_raw(); 115 116 // SAFETY: `devm_add_action` guarantees to call `Self::devres_callback` once `dev` is 117 // detached. 118 let ret = 119 unsafe { bindings::devm_add_action(dev.as_raw(), Some(inner.callback), data as _) }; 120 121 if ret != 0 { 122 // SAFETY: We just created another reference to `inner` in order to pass it to 123 // `bindings::devm_add_action`. If `bindings::devm_add_action` fails, we have to drop 124 // this reference accordingly. 125 let _ = unsafe { Arc::from_raw(data) }; 126 return Err(Error::from_errno(ret)); 127 } 128 129 Ok(inner) 130 } 131 as_ptr(&self) -> *const Self132 fn as_ptr(&self) -> *const Self { 133 self as _ 134 } 135 remove_action(this: &Arc<Self>) -> bool136 fn remove_action(this: &Arc<Self>) -> bool { 137 // SAFETY: 138 // - `self.inner.dev` is a valid `Device`, 139 // - the `action` and `data` pointers are the exact same ones as given to devm_add_action() 140 // previously, 141 // - `self` is always valid, even if the action has been released already. 142 let success = unsafe { 143 bindings::devm_remove_action_nowarn( 144 this.dev.as_raw(), 145 Some(this.callback), 146 this.as_ptr() as _, 147 ) 148 } == 0; 149 150 if success { 151 // SAFETY: We leaked an `Arc` reference to devm_add_action() in `DevresInner::new`; if 152 // devm_remove_action_nowarn() was successful we can (and have to) claim back ownership 153 // of this reference. 154 let _ = unsafe { Arc::from_raw(this.as_ptr()) }; 155 } 156 157 success 158 } 159 160 #[allow(clippy::missing_safety_doc)] devres_callback(ptr: *mut kernel::ffi::c_void)161 unsafe extern "C" fn devres_callback(ptr: *mut kernel::ffi::c_void) { 162 let ptr = ptr as *mut DevresInner<T>; 163 // Devres owned this memory; now that we received the callback, drop the `Arc` and hence the 164 // reference. 165 // SAFETY: Safe, since we leaked an `Arc` reference to devm_add_action() in 166 // `DevresInner::new`. 167 let inner = unsafe { Arc::from_raw(ptr) }; 168 169 if !inner.data.revoke() { 170 // If `revoke()` returns false, it means that `Devres::drop` already started revoking 171 // `inner.data` for us. Hence we have to wait until `Devres::drop()` signals that it 172 // completed revoking `inner.data`. 173 inner.revoke.wait_for_completion(); 174 } 175 } 176 } 177 178 impl<T> Devres<T> { 179 /// Creates a new [`Devres`] instance of the given `data`. The `data` encapsulated within the 180 /// returned `Devres` instance' `data` will be revoked once the device is detached. new(dev: &Device<Bound>, data: T, flags: Flags) -> Result<Self>181 pub fn new(dev: &Device<Bound>, data: T, flags: Flags) -> Result<Self> { 182 let inner = DevresInner::new(dev, data, flags)?; 183 184 Ok(Devres(inner)) 185 } 186 187 /// Same as [`Devres::new`], but does not return a `Devres` instance. Instead the given `data` 188 /// is owned by devres and will be revoked / dropped, once the device is detached. new_foreign_owned(dev: &Device<Bound>, data: T, flags: Flags) -> Result189 pub fn new_foreign_owned(dev: &Device<Bound>, data: T, flags: Flags) -> Result { 190 let _ = DevresInner::new(dev, data, flags)?; 191 192 Ok(()) 193 } 194 195 /// Obtain `&'a T`, bypassing the [`Revocable`]. 196 /// 197 /// This method allows to directly obtain a `&'a T`, bypassing the [`Revocable`], by presenting 198 /// a `&'a Device<Bound>` of the same [`Device`] this [`Devres`] instance has been created with. 199 /// 200 /// # Errors 201 /// 202 /// An error is returned if `dev` does not match the same [`Device`] this [`Devres`] instance 203 /// has been created with. 204 /// 205 /// # Example 206 /// 207 /// ```no_run 208 /// # #![cfg(CONFIG_PCI)] 209 /// # use kernel::{device::Core, devres::Devres, pci}; 210 /// 211 /// fn from_core(dev: &pci::Device<Core>, devres: Devres<pci::Bar<0x4>>) -> Result { 212 /// let bar = devres.access(dev.as_ref())?; 213 /// 214 /// let _ = bar.read32(0x0); 215 /// 216 /// // might_sleep() 217 /// 218 /// bar.write32(0x42, 0x0); 219 /// 220 /// Ok(()) 221 /// } 222 /// ``` access<'a>(&'a self, dev: &'a Device<Bound>) -> Result<&'a T>223 pub fn access<'a>(&'a self, dev: &'a Device<Bound>) -> Result<&'a T> { 224 if self.0.dev.as_raw() != dev.as_raw() { 225 return Err(EINVAL); 226 } 227 228 // SAFETY: `dev` being the same device as the device this `Devres` has been created for 229 // proves that `self.0.data` hasn't been revoked and is guaranteed to not be revoked as 230 // long as `dev` lives; `dev` lives at least as long as `self`. 231 Ok(unsafe { self.0.data.access() }) 232 } 233 234 /// [`Devres`] accessor for [`Revocable::try_access`]. try_access(&self) -> Option<RevocableGuard<'_, T>>235 pub fn try_access(&self) -> Option<RevocableGuard<'_, T>> { 236 self.0.data.try_access() 237 } 238 239 /// [`Devres`] accessor for [`Revocable::try_access_with`]. try_access_with<R, F: FnOnce(&T) -> R>(&self, f: F) -> Option<R>240 pub fn try_access_with<R, F: FnOnce(&T) -> R>(&self, f: F) -> Option<R> { 241 self.0.data.try_access_with(f) 242 } 243 244 /// [`Devres`] accessor for [`Revocable::try_access_with_guard`]. try_access_with_guard<'a>(&'a self, guard: &'a rcu::Guard) -> Option<&'a T>245 pub fn try_access_with_guard<'a>(&'a self, guard: &'a rcu::Guard) -> Option<&'a T> { 246 self.0.data.try_access_with_guard(guard) 247 } 248 } 249 250 impl<T> Drop for Devres<T> { drop(&mut self)251 fn drop(&mut self) { 252 // SAFETY: When `drop` runs, it is guaranteed that nobody is accessing the revocable data 253 // anymore, hence it is safe not to wait for the grace period to finish. 254 if unsafe { self.0.data.revoke_nosync() } { 255 // We revoked `self.0.data` before the devres action did, hence try to remove it. 256 if !DevresInner::remove_action(&self.0) { 257 // We could not remove the devres action, which means that it now runs concurrently, 258 // hence signal that `self.0.data` has been revoked successfully. 259 self.0.revoke.complete_all(); 260 } 261 } 262 } 263 } 264