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 Completion, // 25 }, 26 types::{ 27 ForeignOwnable, 28 Opaque, 29 ScopeGuard, // 30 }, 31 }; 32 33 use pin_init::Wrapper; 34 35 /// [`Devres`] inner data accessed from [`Devres::callback`]. 36 #[pin_data] 37 struct Inner<T: Send> { 38 #[pin] 39 data: Revocable<T>, 40 /// Tracks whether [`Devres::callback`] has been completed. 41 #[pin] 42 devm: Completion, 43 /// Tracks whether revoking [`Self::data`] has been completed. 44 #[pin] 45 revoke: Completion, 46 } 47 48 /// This abstraction is meant to be used by subsystems to containerize [`Device`] bound resources to 49 /// manage their lifetime. 50 /// 51 /// [`Device`] bound resources should be freed when either the resource goes out of scope or the 52 /// [`Device`] is unbound respectively, depending on what happens first. In any case, it is always 53 /// guaranteed that revoking the device resource is completed before the corresponding [`Device`] 54 /// is unbound. 55 /// 56 /// To achieve that [`Devres`] registers a devres callback on creation, which is called once the 57 /// [`Device`] is unbound, revoking access to the encapsulated resource (see also [`Revocable`]). 58 /// 59 /// After the [`Devres`] has been unbound it is not possible to access the encapsulated resource 60 /// anymore. 61 /// 62 /// [`Devres`] users should make sure to simply free the corresponding backing resource in `T`'s 63 /// [`Drop`] implementation. 64 /// 65 /// # Examples 66 /// 67 /// ```no_run 68 /// use kernel::{ 69 /// bindings, 70 /// device::{ 71 /// Bound, 72 /// Device, 73 /// }, 74 /// devres::Devres, 75 /// io::{ 76 /// Io, 77 /// IoKnownSize, 78 /// Mmio, 79 /// MmioRaw, 80 /// PhysAddr, // 81 /// }, 82 /// prelude::*, 83 /// }; 84 /// use core::ops::Deref; 85 /// 86 /// // See also [`pci::Bar`] for a real example. 87 /// struct IoMem<const SIZE: usize>(MmioRaw<SIZE>); 88 /// 89 /// impl<const SIZE: usize> IoMem<SIZE> { 90 /// /// # Safety 91 /// /// 92 /// /// [`paddr`, `paddr` + `SIZE`) must be a valid MMIO region that is mappable into the CPUs 93 /// /// virtual address space. 94 /// unsafe fn new(paddr: usize) -> Result<Self>{ 95 /// // SAFETY: By the safety requirements of this function [`paddr`, `paddr` + `SIZE`) is 96 /// // valid for `ioremap`. 97 /// let addr = unsafe { bindings::ioremap(paddr as PhysAddr, SIZE) }; 98 /// if addr.is_null() { 99 /// return Err(ENOMEM); 100 /// } 101 /// 102 /// Ok(IoMem(MmioRaw::new(addr as usize, SIZE)?)) 103 /// } 104 /// } 105 /// 106 /// impl<const SIZE: usize> Drop for IoMem<SIZE> { 107 /// fn drop(&mut self) { 108 /// // SAFETY: `self.0.addr()` is guaranteed to be properly mapped by `Self::new`. 109 /// unsafe { bindings::iounmap(self.0.addr() as *mut c_void); }; 110 /// } 111 /// } 112 /// 113 /// impl<const SIZE: usize> Deref for IoMem<SIZE> { 114 /// type Target = Mmio<SIZE>; 115 /// 116 /// fn deref(&self) -> &Self::Target { 117 /// // SAFETY: The memory range stored in `self` has been properly mapped in `Self::new`. 118 /// unsafe { Mmio::from_raw(&self.0) } 119 /// } 120 /// } 121 /// # fn no_run(dev: &Device<Bound>) -> Result<(), Error> { 122 /// // SAFETY: Invalid usage for example purposes. 123 /// let iomem = unsafe { IoMem::<{ core::mem::size_of::<u32>() }>::new(0xBAAAAAAD)? }; 124 /// let devres = KBox::pin_init(Devres::new(dev, iomem), GFP_KERNEL)?; 125 /// 126 /// let res = devres.try_access().ok_or(ENXIO)?; 127 /// res.write8(0x42, 0x0); 128 /// # Ok(()) 129 /// # } 130 /// ``` 131 /// 132 /// # Invariants 133 /// 134 /// `Self::inner` is guaranteed to be initialized and is always accessed read-only. 135 #[pin_data(PinnedDrop)] 136 pub struct Devres<T: Send> { 137 dev: ARef<Device>, 138 /// Pointer to [`Self::devres_callback`]. 139 /// 140 /// Has to be stored, since Rust does not guarantee to always return the same address for a 141 /// function. However, the C API uses the address as a key. 142 callback: unsafe extern "C" fn(*mut c_void), 143 /// Contains all the fields shared with [`Self::callback`]. 144 // TODO: Replace with `UnsafePinned`, once available. 145 // 146 // Subsequently, the `drop_in_place()` in `Devres::drop` and `Devres::new` as well as the 147 // explicit `Send` and `Sync' impls can be removed. 148 #[pin] 149 inner: Opaque<Inner<T>>, 150 _add_action: (), 151 } 152 153 impl<T: Send> Devres<T> { 154 /// Creates a new [`Devres`] instance of the given `data`. 155 /// 156 /// The `data` encapsulated within the returned `Devres` instance' `data` will be 157 /// (revoked)[`Revocable`] once the device is detached. 158 pub fn new<'a, E>( 159 dev: &'a Device<Bound>, 160 data: impl PinInit<T, E> + 'a, 161 ) -> impl PinInit<Self, Error> + 'a 162 where 163 T: 'a, 164 Error: From<E>, 165 { 166 try_pin_init!(&this in Self { 167 dev: dev.into(), 168 callback: Self::devres_callback, 169 // INVARIANT: `inner` is properly initialized. 170 inner <- Opaque::pin_init(try_pin_init!(Inner { 171 devm <- Completion::new(), 172 revoke <- Completion::new(), 173 data <- Revocable::new(data), 174 })), 175 // TODO: Replace with "initializer code blocks" [1] once available. 176 // 177 // [1] https://github.com/Rust-for-Linux/pin-init/pull/69 178 _add_action: { 179 // SAFETY: `this` is a valid pointer to uninitialized memory. 180 let inner = unsafe { &raw mut (*this.as_ptr()).inner }; 181 182 // SAFETY: 183 // - `dev.as_raw()` is a pointer to a valid bound device. 184 // - `inner` is guaranteed to be a valid for the duration of the lifetime of `Self`. 185 // - `devm_add_action()` is guaranteed not to call `callback` until `this` has been 186 // properly initialized, because we require `dev` (i.e. the *bound* device) to 187 // live at least as long as the returned `impl PinInit<Self, Error>`. 188 to_result(unsafe { 189 bindings::devm_add_action(dev.as_raw(), Some(*callback), inner.cast()) 190 }).inspect_err(|_| { 191 let inner = Opaque::cast_into(inner); 192 193 // SAFETY: `inner` is a valid pointer to an `Inner<T>` and valid for both reads 194 // and writes. 195 unsafe { core::ptr::drop_in_place(inner) }; 196 })?; 197 }, 198 }) 199 } 200 201 fn inner(&self) -> &Inner<T> { 202 // SAFETY: By the type invairants of `Self`, `inner` is properly initialized and always 203 // accessed read-only. 204 unsafe { &*self.inner.get() } 205 } 206 207 fn data(&self) -> &Revocable<T> { 208 &self.inner().data 209 } 210 211 #[allow(clippy::missing_safety_doc)] 212 unsafe extern "C" fn devres_callback(ptr: *mut kernel::ffi::c_void) { 213 // SAFETY: In `Self::new` we've passed a valid pointer to `Inner` to `devm_add_action()`, 214 // hence `ptr` must be a valid pointer to `Inner`. 215 let inner = unsafe { &*ptr.cast::<Inner<T>>() }; 216 217 // Ensure that `inner` can't be used anymore after we signal completion of this callback. 218 let inner = ScopeGuard::new_with_data(inner, |inner| inner.devm.complete_all()); 219 220 if !inner.data.revoke() { 221 // If `revoke()` returns false, it means that `Devres::drop` already started revoking 222 // `data` for us. Hence we have to wait until `Devres::drop` signals that it 223 // completed revoking `data`. 224 inner.revoke.wait_for_completion(); 225 } 226 } 227 228 fn remove_action(&self) -> bool { 229 // SAFETY: 230 // - `self.dev` is a valid `Device`, 231 // - the `action` and `data` pointers are the exact same ones as given to 232 // `devm_add_action()` previously, 233 (unsafe { 234 bindings::devm_remove_action_nowarn( 235 self.dev.as_raw(), 236 Some(self.callback), 237 core::ptr::from_ref(self.inner()).cast_mut().cast(), 238 ) 239 } == 0) 240 } 241 242 /// Return a reference of the [`Device`] this [`Devres`] instance has been created with. 243 pub fn device(&self) -> &Device { 244 &self.dev 245 } 246 247 /// Obtain `&'a T`, bypassing the [`Revocable`]. 248 /// 249 /// This method allows to directly obtain a `&'a T`, bypassing the [`Revocable`], by presenting 250 /// a `&'a Device<Bound>` of the same [`Device`] this [`Devres`] instance has been created with. 251 /// 252 /// # Errors 253 /// 254 /// An error is returned if `dev` does not match the same [`Device`] this [`Devres`] instance 255 /// has been created with. 256 /// 257 /// # Examples 258 /// 259 /// ```no_run 260 /// #![cfg(CONFIG_PCI)] 261 /// use kernel::{ 262 /// device::Core, 263 /// devres::Devres, 264 /// io::{ 265 /// Io, 266 /// IoKnownSize, // 267 /// }, 268 /// pci, // 269 /// }; 270 /// 271 /// fn from_core(dev: &pci::Device<Core>, devres: Devres<pci::Bar<0x4>>) -> Result { 272 /// let bar = devres.access(dev.as_ref())?; 273 /// 274 /// let _ = bar.read32(0x0); 275 /// 276 /// // might_sleep() 277 /// 278 /// bar.write32(0x42, 0x0); 279 /// 280 /// Ok(()) 281 /// } 282 /// ``` 283 pub fn access<'a>(&'a self, dev: &'a Device<Bound>) -> Result<&'a T> { 284 if self.dev.as_raw() != dev.as_raw() { 285 return Err(EINVAL); 286 } 287 288 // SAFETY: `dev` being the same device as the device this `Devres` has been created for 289 // proves that `self.data` hasn't been revoked and is guaranteed to not be revoked as long 290 // as `dev` lives; `dev` lives at least as long as `self`. 291 Ok(unsafe { self.data().access() }) 292 } 293 294 /// [`Devres`] accessor for [`Revocable::try_access`]. 295 pub fn try_access(&self) -> Option<RevocableGuard<'_, T>> { 296 self.data().try_access() 297 } 298 299 /// [`Devres`] accessor for [`Revocable::try_access_with`]. 300 pub fn try_access_with<R, F: FnOnce(&T) -> R>(&self, f: F) -> Option<R> { 301 self.data().try_access_with(f) 302 } 303 304 /// [`Devres`] accessor for [`Revocable::try_access_with_guard`]. 305 pub fn try_access_with_guard<'a>(&'a self, guard: &'a rcu::Guard) -> Option<&'a T> { 306 self.data().try_access_with_guard(guard) 307 } 308 } 309 310 // SAFETY: `Devres` can be send to any task, if `T: Send`. 311 unsafe impl<T: Send> Send for Devres<T> {} 312 313 // SAFETY: `Devres` can be shared with any task, if `T: Sync`. 314 unsafe impl<T: Send + Sync> Sync for Devres<T> {} 315 316 #[pinned_drop] 317 impl<T: Send> PinnedDrop for Devres<T> { 318 fn drop(self: Pin<&mut Self>) { 319 // SAFETY: When `drop` runs, it is guaranteed that nobody is accessing the revocable data 320 // anymore, hence it is safe not to wait for the grace period to finish. 321 if unsafe { self.data().revoke_nosync() } { 322 // We revoked `self.data` before the devres action did, hence try to remove it. 323 if !self.remove_action() { 324 // We could not remove the devres action, which means that it now runs concurrently, 325 // hence signal that `self.data` has been revoked by us successfully. 326 self.inner().revoke.complete_all(); 327 328 // Wait for `Self::devres_callback` to be done using this object. 329 self.inner().devm.wait_for_completion(); 330 } 331 } else { 332 // `Self::devres_callback` revokes `self.data` for us, hence wait for it to be done 333 // using this object. 334 self.inner().devm.wait_for_completion(); 335 } 336 337 // INVARIANT: At this point it is guaranteed that `inner` can't be accessed any more. 338 // 339 // SAFETY: `inner` is valid for dropping. 340 unsafe { core::ptr::drop_in_place(self.inner.get()) }; 341 } 342 } 343 344 /// Consume `data` and [`Drop::drop`] `data` once `dev` is unbound. 345 fn register_foreign<P>(dev: &Device<Bound>, data: P) -> Result 346 where 347 P: ForeignOwnable + Send + 'static, 348 { 349 let ptr = data.into_foreign(); 350 351 #[allow(clippy::missing_safety_doc)] 352 unsafe extern "C" fn callback<P: ForeignOwnable>(ptr: *mut kernel::ffi::c_void) { 353 // SAFETY: `ptr` is the pointer to the `ForeignOwnable` leaked above and hence valid. 354 drop(unsafe { P::from_foreign(ptr.cast()) }); 355 } 356 357 // SAFETY: 358 // - `dev.as_raw()` is a pointer to a valid and bound device. 359 // - `ptr` is a valid pointer the `ForeignOwnable` devres takes ownership of. 360 to_result(unsafe { 361 // `devm_add_action_or_reset()` also calls `callback` on failure, such that the 362 // `ForeignOwnable` is released eventually. 363 bindings::devm_add_action_or_reset(dev.as_raw(), Some(callback::<P>), ptr.cast()) 364 }) 365 } 366 367 /// Encapsulate `data` in a [`KBox`] and [`Drop::drop`] `data` once `dev` is unbound. 368 /// 369 /// # Examples 370 /// 371 /// ```no_run 372 /// use kernel::{ 373 /// device::{ 374 /// Bound, 375 /// Device, // 376 /// }, 377 /// devres, // 378 /// }; 379 /// 380 /// /// Registration of e.g. a class device, IRQ, etc. 381 /// struct Registration; 382 /// 383 /// impl Registration { 384 /// fn new() -> Self { 385 /// // register 386 /// 387 /// Self 388 /// } 389 /// } 390 /// 391 /// impl Drop for Registration { 392 /// fn drop(&mut self) { 393 /// // unregister 394 /// } 395 /// } 396 /// 397 /// fn from_bound_context(dev: &Device<Bound>) -> Result { 398 /// devres::register(dev, Registration::new(), GFP_KERNEL) 399 /// } 400 /// ``` 401 pub fn register<T, E>(dev: &Device<Bound>, data: impl PinInit<T, E>, flags: Flags) -> Result 402 where 403 T: Send + 'static, 404 Error: From<E>, 405 { 406 let data = KBox::pin_init(data, flags)?; 407 408 register_foreign(dev, data) 409 } 410