projects/linux·blob v7.2 · refs

434 lines · 14.1 KiB

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