projects/linux·blob v7.1-rc4 · refs

433 lines · 14.0 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/// 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/// ```
125pub 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.
137mod 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
187impl<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`.
347unsafe impl<T: Send> Send for Devres<T> {}
348
349// SAFETY: `Devres` can be shared with any task, if `T: Sync`.
350unsafe impl<T: Send + Sync> Sync for Devres<T> {}
351
352impl<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.
369fn register_foreign<P>(dev: &Device<Bound>, data: P) -> Result
370where
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/// ```
425pub fn register<T, E>(dev: &Device<Bound>, data: impl PinInit<T, E>, flags: Flags) -> Result
426where
427 T: Send + 'static,
428 Error: From<E>,
429{
430 let data = KBox::pin_init(data, flags)?;
431
432 register_foreign(dev, data)
433}