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::{ 27 ForeignOwnable, 28 Opaque, // 29 }, 30 }; 31 32 /// Inner type that embeds a `struct devres_node` and the `Revocable<T>`. 33 #[repr(C)] 34 #[pin_data] 35 struct Inner<T> { 36 #[pin] 37 node: Opaque<bindings::devres_node>, 38 #[pin] 39 data: Revocable<T>, 40 } 41 42 /// This abstraction is meant to be used by subsystems to containerize [`Device`] bound resources to 43 /// manage their lifetime. 44 /// 45 /// [`Device`] bound resources should be freed when either the resource goes out of scope or the 46 /// [`Device`] is unbound respectively, depending on what happens first. In any case, it is always 47 /// guaranteed that revoking the device resource is completed before the corresponding [`Device`] 48 /// is unbound. 49 /// 50 /// To achieve that [`Devres`] registers a devres callback on creation, which is called once the 51 /// [`Device`] is unbound, revoking access to the encapsulated resource (see also [`Revocable`]). 52 /// 53 /// After the [`Devres`] has been unbound it is not possible to access the encapsulated resource 54 /// anymore. 55 /// 56 /// [`Devres`] users should make sure to simply free the corresponding backing resource in `T`'s 57 /// [`Drop`] implementation. 58 /// 59 /// # Examples 60 /// 61 /// ```no_run 62 /// use kernel::{ 63 /// bindings, 64 /// device::{ 65 /// Bound, 66 /// Device, 67 /// }, 68 /// devres::Devres, 69 /// io::{ 70 /// Io, 71 /// IoKnownSize, 72 /// Mmio, 73 /// MmioRaw, 74 /// PhysAddr, // 75 /// }, 76 /// prelude::*, 77 /// }; 78 /// use core::ops::Deref; 79 /// 80 /// // See also [`pci::Bar`] for a real example. 81 /// struct IoMem<const SIZE: usize>(MmioRaw<SIZE>); 82 /// 83 /// impl<const SIZE: usize> IoMem<SIZE> { 84 /// /// # Safety 85 /// /// 86 /// /// [`paddr`, `paddr` + `SIZE`) must be a valid MMIO region that is mappable into the CPUs 87 /// /// virtual address space. 88 /// unsafe fn new(paddr: usize) -> Result<Self>{ 89 /// // SAFETY: By the safety requirements of this function [`paddr`, `paddr` + `SIZE`) is 90 /// // valid for `ioremap`. 91 /// let addr = unsafe { bindings::ioremap(paddr as PhysAddr, SIZE) }; 92 /// if addr.is_null() { 93 /// return Err(ENOMEM); 94 /// } 95 /// 96 /// Ok(IoMem(MmioRaw::new(addr as usize, SIZE)?)) 97 /// } 98 /// } 99 /// 100 /// impl<const SIZE: usize> Drop for IoMem<SIZE> { 101 /// fn drop(&mut self) { 102 /// // SAFETY: `self.0.addr()` is guaranteed to be properly mapped by `Self::new`. 103 /// unsafe { bindings::iounmap(self.0.addr() as *mut c_void); }; 104 /// } 105 /// } 106 /// 107 /// impl<const SIZE: usize> Deref for IoMem<SIZE> { 108 /// type Target = Mmio<SIZE>; 109 /// 110 /// fn deref(&self) -> &Self::Target { 111 /// // SAFETY: The memory range stored in `self` has been properly mapped in `Self::new`. 112 /// unsafe { Mmio::from_raw(&self.0) } 113 /// } 114 /// } 115 /// # fn no_run(dev: &Device<Bound>) -> Result<(), Error> { 116 /// // SAFETY: Invalid usage for example purposes. 117 /// let iomem = unsafe { IoMem::<{ core::mem::size_of::<u32>() }>::new(0xBAAAAAAD)? }; 118 /// let devres = Devres::new(dev, iomem)?; 119 /// 120 /// let res = devres.try_access().ok_or(ENXIO)?; 121 /// res.write8(0x42, 0x0); 122 /// # Ok(()) 123 /// # } 124 /// ``` 125 pub struct Devres<T: Send> { 126 dev: ARef<Device>, 127 inner: Arc<Inner<T>>, 128 } 129 130 // Calling the FFI functions from the `base` module directly from the `Devres<T>` impl may result in 131 // them being called directly from driver modules. This happens since the Rust compiler will use 132 // monomorphisation, so it might happen that functions are instantiated within the calling driver 133 // module. For now, work around this with `#[inline(never)]` helpers. 134 // 135 // TODO: Remove once a more generic solution has been implemented. For instance, we may be able to 136 // leverage `bindgen` to take care of this depending on whether a symbol is (already) exported. 137 mod base { 138 use kernel::{ 139 bindings, 140 prelude::*, // 141 }; 142 143 #[inline(never)] 144 #[allow(clippy::missing_safety_doc)] 145 pub(super) unsafe fn devres_node_init( 146 node: *mut bindings::devres_node, 147 release: bindings::dr_node_release_t, 148 free: bindings::dr_node_free_t, 149 ) { 150 // SAFETY: Safety requirements are the same as `bindings::devres_node_init`. 151 unsafe { bindings::devres_node_init(node, release, free) } 152 } 153 154 #[inline(never)] 155 #[allow(clippy::missing_safety_doc)] 156 pub(super) unsafe fn devres_set_node_dbginfo( 157 node: *mut bindings::devres_node, 158 name: *const c_char, 159 size: usize, 160 ) { 161 // SAFETY: Safety requirements are the same as `bindings::devres_set_node_dbginfo`. 162 unsafe { bindings::devres_set_node_dbginfo(node, name, size) } 163 } 164 165 #[inline(never)] 166 #[allow(clippy::missing_safety_doc)] 167 pub(super) unsafe fn devres_node_add( 168 dev: *mut bindings::device, 169 node: *mut bindings::devres_node, 170 ) { 171 // SAFETY: Safety requirements are the same as `bindings::devres_node_add`. 172 unsafe { bindings::devres_node_add(dev, node) } 173 } 174 175 #[must_use] 176 #[inline(never)] 177 #[allow(clippy::missing_safety_doc)] 178 pub(super) unsafe fn devres_node_remove( 179 dev: *mut bindings::device, 180 node: *mut bindings::devres_node, 181 ) -> bool { 182 // SAFETY: Safety requirements are the same as `bindings::devres_node_remove`. 183 unsafe { bindings::devres_node_remove(dev, node) } 184 } 185 } 186 187 impl<T: Send> Devres<T> { 188 /// Creates a new [`Devres`] instance of the given `data`. 189 /// 190 /// The `data` encapsulated within the returned `Devres` instance' `data` will be 191 /// (revoked)[`Revocable`] once the device is detached. 192 pub fn new<E>(dev: &Device<Bound>, data: impl PinInit<T, E>) -> Result<Self> 193 where 194 Error: From<E>, 195 { 196 let inner = Arc::pin_init::<Error>( 197 try_pin_init!(Inner { 198 node <- Opaque::ffi_init(|node: *mut bindings::devres_node| { 199 // SAFETY: `node` is a valid pointer to an uninitialized `struct devres_node`. 200 unsafe { 201 base::devres_node_init( 202 node, 203 Some(Self::devres_node_release), 204 Some(Self::devres_node_free_node), 205 ) 206 }; 207 208 // SAFETY: `node` is a valid pointer to an uninitialized `struct devres_node`. 209 unsafe { 210 base::devres_set_node_dbginfo( 211 node, 212 // TODO: Use `core::any::type_name::<T>()` once it is a `const fn`, 213 // such that we can convert the `&str` to a `&CStr` at compile-time. 214 c"Devres<T>".as_char_ptr(), 215 core::mem::size_of::<Revocable<T>>(), 216 ) 217 }; 218 }), 219 data <- Revocable::new(data), 220 }), 221 GFP_KERNEL, 222 )?; 223 224 // SAFETY: 225 // - `dev` is a valid pointer to a bound `struct device`. 226 // - `node` is a valid pointer to a `struct devres_node`. 227 // - `devres_node_add()` is guaranteed not to call `devres_node_release()` for the entire 228 // lifetime of `dev`. 229 unsafe { base::devres_node_add(dev.as_raw(), inner.node.get()) }; 230 231 // Take additional reference count for `devres_node_add()`. 232 core::mem::forget(inner.clone()); 233 234 Ok(Self { 235 dev: dev.into(), 236 inner, 237 }) 238 } 239 240 fn data(&self) -> &Revocable<T> { 241 &self.inner.data 242 } 243 244 #[allow(clippy::missing_safety_doc)] 245 unsafe extern "C" fn devres_node_release( 246 _dev: *mut bindings::device, 247 node: *mut bindings::devres_node, 248 ) { 249 let node = Opaque::cast_from(node); 250 251 // SAFETY: `node` is in the same allocation as its container. 252 let inner = unsafe { kernel::container_of!(node, Inner<T>, node) }; 253 254 // SAFETY: `inner` is a valid `Inner<T>` pointer. 255 let inner = unsafe { &*inner }; 256 257 inner.data.revoke(); 258 } 259 260 #[allow(clippy::missing_safety_doc)] 261 unsafe extern "C" fn devres_node_free_node(node: *mut bindings::devres_node) { 262 let node = Opaque::cast_from(node); 263 264 // SAFETY: `node` is in the same allocation as its container. 265 let inner = unsafe { kernel::container_of!(node, Inner<T>, node) }; 266 267 // SAFETY: `inner` points to the entire `Inner<T>` allocation. 268 drop(unsafe { Arc::from_raw(inner) }); 269 } 270 271 fn remove_node(&self) -> bool { 272 // SAFETY: 273 // - `self.device().as_raw()` is a valid pointer to a bound `struct device`. 274 // - `self.inner.node.get()` is a valid pointer to a `struct devres_node`. 275 unsafe { base::devres_node_remove(self.device().as_raw(), self.inner.node.get()) } 276 } 277 278 /// Return a reference of the [`Device`] this [`Devres`] instance has been created with. 279 pub fn device(&self) -> &Device { 280 &self.dev 281 } 282 283 /// Obtain `&'a T`, bypassing the [`Revocable`]. 284 /// 285 /// This method allows to directly obtain a `&'a T`, bypassing the [`Revocable`], by presenting 286 /// a `&'a Device<Bound>` of the same [`Device`] this [`Devres`] instance has been created with. 287 /// 288 /// # Errors 289 /// 290 /// An error is returned if `dev` does not match the same [`Device`] this [`Devres`] instance 291 /// has been created with. 292 /// 293 /// # Examples 294 /// 295 /// ```no_run 296 /// #![cfg(CONFIG_PCI)] 297 /// use kernel::{ 298 /// device::Core, 299 /// devres::Devres, 300 /// io::{ 301 /// Io, 302 /// IoKnownSize, // 303 /// }, 304 /// pci, // 305 /// }; 306 /// 307 /// fn from_core(dev: &pci::Device<Core>, devres: Devres<pci::Bar<0x4>>) -> Result { 308 /// let bar = devres.access(dev.as_ref())?; 309 /// 310 /// let _ = bar.read32(0x0); 311 /// 312 /// // might_sleep() 313 /// 314 /// bar.write32(0x42, 0x0); 315 /// 316 /// Ok(()) 317 /// } 318 /// ``` 319 pub fn access<'a>(&'a self, dev: &'a Device<Bound>) -> Result<&'a T> { 320 if self.dev.as_raw() != dev.as_raw() { 321 return Err(EINVAL); 322 } 323 324 // SAFETY: `dev` being the same device as the device this `Devres` has been created for 325 // proves that `self.data` hasn't been revoked and is guaranteed to not be revoked as long 326 // as `dev` lives; `dev` lives at least as long as `self`. 327 Ok(unsafe { self.data().access() }) 328 } 329 330 /// [`Devres`] accessor for [`Revocable::try_access`]. 331 pub fn try_access(&self) -> Option<RevocableGuard<'_, T>> { 332 self.data().try_access() 333 } 334 335 /// [`Devres`] accessor for [`Revocable::try_access_with`]. 336 pub fn try_access_with<R, F: FnOnce(&T) -> R>(&self, f: F) -> Option<R> { 337 self.data().try_access_with(f) 338 } 339 340 /// [`Devres`] accessor for [`Revocable::try_access_with_guard`]. 341 pub fn try_access_with_guard<'a>(&'a self, guard: &'a rcu::Guard) -> Option<&'a T> { 342 self.data().try_access_with_guard(guard) 343 } 344 } 345 346 // SAFETY: `Devres` can be send to any task, if `T: Send`. 347 unsafe impl<T: Send> Send for Devres<T> {} 348 349 // SAFETY: `Devres` can be shared with any task, if `T: Sync`. 350 unsafe impl<T: Send + Sync> Sync for Devres<T> {} 351 352 impl<T: Send> Drop for Devres<T> { 353 fn drop(&mut self) { 354 // SAFETY: When `drop` runs, it is guaranteed that nobody is accessing the revocable data 355 // anymore, hence it is safe not to wait for the grace period to finish. 356 if unsafe { self.data().revoke_nosync() } { 357 // We revoked `self.data` before devres did, hence try to remove it. 358 if self.remove_node() { 359 // SAFETY: In `Self::new` we have taken an additional reference count of `self.data` 360 // for `devres_node_add()`. Since `remove_node()` was successful, we have to drop 361 // this additional reference count. 362 drop(unsafe { Arc::from_raw(Arc::as_ptr(&self.inner)) }); 363 } 364 } 365 } 366 } 367 368 /// Consume `data` and [`Drop::drop`] `data` once `dev` is unbound. 369 fn register_foreign<P>(dev: &Device<Bound>, data: P) -> Result 370 where 371 P: ForeignOwnable + Send + 'static, 372 { 373 let ptr = data.into_foreign(); 374 375 #[allow(clippy::missing_safety_doc)] 376 unsafe extern "C" fn callback<P: ForeignOwnable>(ptr: *mut kernel::ffi::c_void) { 377 // SAFETY: `ptr` is the pointer to the `ForeignOwnable` leaked above and hence valid. 378 drop(unsafe { P::from_foreign(ptr.cast()) }); 379 } 380 381 // SAFETY: 382 // - `dev.as_raw()` is a pointer to a valid and bound device. 383 // - `ptr` is a valid pointer the `ForeignOwnable` devres takes ownership of. 384 to_result(unsafe { 385 // `devm_add_action_or_reset()` also calls `callback` on failure, such that the 386 // `ForeignOwnable` is released eventually. 387 bindings::devm_add_action_or_reset(dev.as_raw(), Some(callback::<P>), ptr.cast()) 388 }) 389 } 390 391 /// Encapsulate `data` in a [`KBox`] and [`Drop::drop`] `data` once `dev` is unbound. 392 /// 393 /// # Examples 394 /// 395 /// ```no_run 396 /// use kernel::{ 397 /// device::{ 398 /// Bound, 399 /// Device, // 400 /// }, 401 /// devres, // 402 /// }; 403 /// 404 /// /// Registration of e.g. a class device, IRQ, etc. 405 /// struct Registration; 406 /// 407 /// impl Registration { 408 /// fn new() -> Self { 409 /// // register 410 /// 411 /// Self 412 /// } 413 /// } 414 /// 415 /// impl Drop for Registration { 416 /// fn drop(&mut self) { 417 /// // unregister 418 /// } 419 /// } 420 /// 421 /// fn from_bound_context(dev: &Device<Bound>) -> Result { 422 /// devres::register(dev, Registration::new(), GFP_KERNEL) 423 /// } 424 /// ``` 425 pub fn register<T, E>(dev: &Device<Bound>, data: impl PinInit<T, E>, flags: Flags) -> Result 426 where 427 T: Send + 'static, 428 Error: From<E>, 429 { 430 let data = KBox::pin_init(data, flags)?; 431 432 register_foreign(dev, data) 433 } 434