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::{ 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 /// ``` 112 pub 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 122 impl<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`. 254 unsafe impl<T: Send> Send for Devres<T> {} 255 256 // SAFETY: `Devres` can be shared with any task, if `T: Sync`. 257 unsafe impl<T: Send + Sync> Sync for Devres<T> {} 258 259 impl<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. 276 fn register_foreign<P>(dev: &Device<Bound>, data: P) -> Result 277 where 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 /// ``` 332 pub fn register<T, E>(dev: &Device<Bound>, data: impl PinInit<T, E>, flags: Flags) -> Result 333 where 334 T: Send + 'static, 335 Error: From<E>, 336 { 337 let data = KBox::pin_init(data, flags)?; 338 339 register_foreign(dev, data) 340 } 341